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Chapter 1 Introduction 


The Meridian Ada DOS Environment Library is a set of Ada packages for use with the Meridian Ada* 
compiler that provides an interface to PC-DOS version 2.1 or later. The MeridianAda DOS Environment 
Library allows you to use most of the PC—DOS system calls, plus screen management and other BIOS 
functions. Excluded system calls include those that are obsolete in the newer versions of PC-DOS or are 
designed for use only on PC networks. 


Note that the BIOS interface functions are designed to operate with the standard IBM PC BIOS. 


Some operations are appropriate only for DOS 3.0 or later; these are marked as such. Any attempt to use these 
operations on earlier versions of DOS causes an exception to be raised. 


Some of the highlights of the MeridianAda DOS Environment Library include: 


a 


absolute_disk Provides procedures to read and write on disk devices without regard to 
the file system structure imposed by PC-DOS. 


fbox Provides the procedures for drawing boxes on the text screen. 
common_display types | Contains type declarations for the various packages that handle display 
operations. 
Provides operations to move a text mode cursor, to get the current cursor 
coordinates, and to alter the visibility or form of the cursor. 
Provides subprograms that create, delete, and change directories. 
Provides operations such as flushing file buffers, getting default disk 
drive ID, and returning information about the disk drive. 
Contains type declarations used by the disk and directory operation pack- 
; ages. 
equipment Provides a function that enumerates the system—recognized devices and 
facilities present on the machine. 
Provides PC-DOS status declarations and for version 3.0 or later of PC- 
DOS, a procedure to get extended status information. 
£file_io Provides input/output, file attribute manipulation, and wildcard search 
operations. 


low lao Emap 
}memory =i Provides functions to allocate and deallocate memory. 
[port — Allows byte or word input and output to the specified port. 


memory 
program_control Provides functions that exert control over the executing program that ex- 
ecute other programs, or that obtain information about resident programs. 


*The DOS Environment Library can also be used with the AdaGraduate Compiler. Please note that references 
to the Meridian Ada Compiler also apply to the AdaGraduate Compiler. 
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a 
Provides a facility for determining the revision number of PC-DOS. 
[tine __| Provides procedures to get and set the curent system date and ime. | 
[ety ____| Provides operations on the console teminal display and Keyboard. 


video Provides various output and control functions for the Monochrome, Col- 
or Graphics and Extended Graphics Adapter Cards. 
1.1 Scope of This Document 


It is assumed that you are familiar with PC~DOS and the Meridian Ada compiler and associated library 
management tools. This document covers only material required to use the packages; information about 
the Ada programming language, about most low-level functional aspects of the PC-DOS system calls, 
and most aspects of the Meridian Ada compiler is outside the scope of this document. Other documents that 
cover the aforementioned material include: 


¢ The Meridian Ada Compiler User's Guide. This document describes operation of 
the compiler and associated tools. ; 


e Reference Manual for the Ada Programming Language ANSI/MIL-STD-1815A 
(the LRM). This document describes the Ada language. 


@ Ada For Programmers (Prentice-Hall, 1983). This book by Meridian co-founders 
Eric Olsen and Stephen Whitehill provides an introduction to Ada programming 
for practicing programmers. 


¢ Microsoft MS-DOS Operating System Programmer's Reference (available from 
Microsoft Corporation). This document covers DOS system calls in great detail. 


1.2 Document Organization 


The descriptions of the packages are organized alphabetically by package name. Each package is presented 
with its specification, a brief description of its uses, and a discussion of the details of the package. 
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Chapter 2 Installing the DOS Environment Library 


a 


2.1 Installation Procedure 


Prior to installing the Meridian Ada DOS Environment Library, the Ada compiler must be installed. 


This installation procedure assumes that you will install the DOS Environment Library on the same hard disk — 
drive and in the same top-level directory in which you installed the compiler. If you do not install the DOS 
Environment Library in that place (not recommended) the installation procedure will work to a point, but the 
link entry in the DOS Environment Library library database file (ada . Lib) will have to be linked to the stan- 
dard distribution library (paclib\ada .14b). An example of how to do this is given in section 2.2. 


To perform the installation procedure: 
1. Reboot the operating system. 
2. Insert the distribution diskette into diskette drive a:. 
3. Run the installation program as: 
a:install d:\directory 


The command line arguments to instal are d, a hard disk drive letter, and directory. Note that 
directory must start with a backslash (‘\”). The hard disk and directory that you select should be 
the same as were selected for installation of the compiler (e.g. c: \ada). 


The installation procedure should take only a few minutes. If there is not enough space on the destination disk 
to accommodate all the files, the installation will fail. The files are installed ina sub-directory named dosenv 
below the top-level directory given to the install command. If dosenv does not exist on the destination 
disk, then the install command creates that directory. If the directory already exists, a harmless error mes- 
sage is printed, but installation proceeds. 


2.2 Adjusting an Unusual Installation 


If you did not install the DOS Environment Library using the same top-level directory in which you installed 
the compiler, you should have gotten a waming message. In this case, the link entry in the DOS Environment 
Library library database file (ada .1ib) must to be modified to reflect the actual location of the standard 
distribution library (paclib\ada.1ib). 


You do not need to do this if you used the same top-level directory in which you installed the compiler. 


The adjustment to the DOS Environment Library library is made by using the lnlib command, as in this 
example: 


e: 

ed \stuff\dosenv 

rem — The above two commands assume that e:\stuff was 

rem -- the top-level directory specified to the install command. 
lnlib -r c:\ada\paclib\ada.lib e:\ada\paclib\ada.lib 


This example assumes that you originally installed the compiler using e : \ada as the installation directory 
and that you installed the DOS Environment Library ine: \stuf£. Note thatthe 1n1ib command in this 
example replaces a pre-existing library link entry. | 
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2.3 Creating Library Links 


Once the software is installed, itis necessary to make the appropriate link in each local library where the pack- 
age is to be used. If the software is installed in the same top-level directory in which the compiler was in- 
stalled, then the installation procedure automatically modifies the behavior of the new1ib command so that 
the DOS Environment Library library is linked into every newly created local library. If the software is in- 
stalled elsewhere and you want the same modification made to the new1ib command, then you should per- 
form the following procedures. 


Modify the newlib .bat file to link the DOS Environment Library library whenever the new1ib com- 
mand is invoked. For example, this command could be added to the end of the newlib. bat file: 


lnlib c: \ada\dosenv\ada.lib 


The new1lib . bat file is located in the bin directory below the Meridian Ada compiler installation directo- 
ry. In this example, it is assumed that c: \ada is the top-level directory where the Meridian Ada compiler 
was installed. 


Note: Always make a backup of the old newlib.bat file before modifying it. 
2.4 Verifying Correct Installation 


Below the top-level directory given to insta11, the directory dosenv and test should have been created 
by the installation procedure for the DOS Environment Library. Note that if you installed the DOS Environ- 
ment Library in the same top-level directory in which you originally installed the compiler (e.g. c: \ada) 
the test directory already existed. 


There should be a number of files present in the dosenv directory: *.1lib, *.aar, and *.int. 
In the test directory these two source files should be present: 


boxdemo.ada Draws boxes on the screen. In addition to demonstrating several of the DOS Envi- 
ronment packages, it also demonstrates Meridian Ada tasking. 
NOTE: Because this program uses the screen management packages, it requires a 
100% IBM—compatible BIOS. 


envdisp.ada Displays current environment settings. This prints the current directory, the names of 
files in the current directory, environment variable values, and other environment- 
specific information. 
To compile and run these demonstration programs, follow these steps: 
1. Gotothe test directory and enter a link in the local library to the DOS Environ- 
ment Library library, as in this example: 
c: 
cd ada\test 
newlib 
inlib c: \ada\dosenv\ada.lib 
rem --If newlib has been modified to do this 
rem --already, you can skip the lnlib command. 
This example assumes that the DOS Environment Library was installed using c: \ada as the 
top-level directory. Use whatever path is appropriate for your installation. 
2. Compile and link the first sample program: 
ada boxdemo. ada | 
bamp boxdemo 
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3. Assuming that all went well, run the sample program as: 
boxdemo 


This should clear the display and draw some boxes. If it cannot do this with the current display 
mode, an error message is printed. Regardless of precisely what is displayed, something should 


happen. 
4, Compile and link the second sample program: 
ada envdisp.ada 
bamp envdisp 
5. Assuming that all went well, run the second sample program as: 


envdisp 


This should print various information about the current environment, as detailed in the program 
description above. Regardless of precisely what is displayed, something should happen. 


If these programs work correctly (within their operational parameters), then the DOS Environment Library 
was probably loaded correctly and is ready for further use in other programs. 


{ 
i 
| 
| 
| 
| 
i 
| 
| 
| 
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Chapter 3 Package Absolute_Disk 


Package absolute_disk provides procedures to read and write on disk devices without rene to the 
file system structure imposed by PC-DOS. 


SPECIFICATION 


with disk types, 
system; 
package absolute_disk is 
type status is ( 
ok, bad_command, 
address_not_found, write_protected, | 
sector not found, dma_ failure, 


bad_cre, controller failed, 
seek_failed, time_out, 
unknown _error 


); 


procedure read ( 


from_drive : disk_types.drive id; 
number of sectors : natural; 

starting logical_sector : natural; 
transfer_area : system. address; 
error : out status 


); 
procedure write ( 


from_drive : disk types.drive_: id; 
number of sectors : natural; 

starting logical sector : natural; 
transfer_area : system. address; 
error : out status 


); 
end absolute_disk; 


3.1 Procedure Read 


The procedure read gets data from specific logical disk sectors, ignoring the file system structure of the disk. 
The selected disk seeks to the starting logical_sector, reads the number_of_sectors specified into the 
memory location starting at the transfer_area, and retums an error status. If no error occurs, sta— 
tus’ (ok) is retuned. Any other status value indicates some kind of error. 


procedure read ( 


from_drive : disk types.drive_ id; 
number of sectors : natural; 

starting logical sector : natural; 
transfer_area : : system. address; 
error : out status 
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The number of bytes read per sector is typically 512, but this number may vary according to the disk device 
Logical sectors are numbered sequentially from track 0, head 0, sector 1, and continue until the last sector, 
the last sector number being a characteristic of a specific type of disk device. As logical sector numbers 
increase, the internal sector, head, and track numbers increment (in that order). 


The read service works with logical drives as opposed to true physical drives. An attempt to read from a 
logical drive that has no corresponding physical drive or disk area (i.e is not installed) has unpredictable re- 
sults. 


This call corresponds to Interrupt 16#25#. 
3.2 Procedure Write 


The procedure write puts data to specific logical disk sectors, ignoring the file system structure of the disk. 
The selected disk seeks to the starting logical_sector, writes the number_of_sectors specified from the 
memory location starting at the transfer_area, and retums an error status. Ifno error occurs, status’ (ok) 
is returned. Any other status value indicates some kind of error. _ 


procedure write ( 


from_drive : disk_types.drive_id; 
number_of_sectors > natural; 

starting logical sector : natural; 
transfer_area : system. address; 
error : out status 


); . 
The number of bytes written per sector is typically 512, but this number may vary according to the disk device 
type. 


Logical sectors are numbered sequentially from track 0, head 0, sector 1, and continue until the last sector, 
the last sector number being a characteristic of a specific type of disk device. As logical sector numbers 
increase, the intemal sector, head, and track numbers increment (in that order). 


The write service works with logical drives as opposed to true physical drives. An attempt to write to a 
logical drive that has no corresponding physical drive or disk area (i.¢ is not installed) has unpredictable re- 
sults. 


** WARNING ** Writing sectors directly to a disk in this way is likely to destroy any previous disk file struc- 
ture. 


This call corresponds to Interrupt 16#26#. 
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Chapter 4 Package Box : 


The package box provides procedures for drawing boxes on the text screen either using the box—drawing 
characters (tops, bottoms, sides, and comers) or using a single selected character. 


The routines in package box call many DOS functions; there is no correspondence to a single DOS function 
as with most of the other subprograms in the Meridian Ada DOS Environment Library. : 


SPECIFICATION 
with common_display types; 
use common display types; 
package box is 


type part is ( 

north, northeast, east, southeast, 

south, southwest, west, northwest 

); 
type user_definition is array (part) of extended_ascii; 
type simple_kind is ( 

single_sided, double sided, 

single top, double_top 

); 


procedure draw ( 


upper_left_row : row_range; 

upper_left column : column_range; 
lower_right_row : row_range; 
lower_right_column : column_range; 

kind : simple_kind := single_sided; 
attribute : display attribute := ( 


foreground => white, 

background => black, 

blink => false 

); 
page : display page :z 0 
)? 
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procedure draw ( 


upper left row : row range; 
upper_left_colum : column range; 
lower_right_row : sow _range; 
lower_right_column : column range; 
box_definition : user_definition; 
attribute : display attribute : 


foreground => white, 
background => black, 


blink => false 
pase : display page 
ea box; 
4.1 Type Part 


Type part is an enumeration used to describe the parts of a box. 


type part is ( 
north, northeast, east, southeast, 
south, southwest, west, northwest 


); 


The elements are compass points and have these correspondences: 


North The top of a box 

NorthEast The upper right comer of a box 
East The right side of a box 
SouthEast The lower right comer of a box 
South The bottom of a box 
SouthWest = The lower left corner of a box 
West The left side of a box 


NorthWest The upper left comer of a box 
These are illustrated as: 


North 
NorthWest 
West 
SouthWest 
South 
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SouthEast 


Package box 


4.2 Type User_Definition 


Type user_definition is used to describe tal character i is used for each part of a box. 
type user_definition is array (part). of extended ascii; 


Some particularly useful characters for drawing boxes are in the range 179.. 218. Ifno table showing these 
characters is available, then the following program will print them out: 


with video; 
procedure printchars is 
begin 
for char in 179 .. 218 loop 
video.write_tty (char); -- write to page 0 
video.write tty (’ '); -- separate with space 
end loop; 
end printchars; 


4.3 Type Simple_Kind © 


Type simple_kind is used to select a pre-defined box style. 


type simple_kind is ( 
single_sided, double sided, 
single top, double top 
); 


The default box—drawing characters are the IBM PC characters used to draw connecting horizontal 
and vertical lines and comers, with either single rules or double rules. 


The box styles corresponding to each simple_kind are: 
single sided single—rule lines all around 
double_sided double-tule lines all around 
single top single—rule lines on top and -bottom; double rule lines on the sides 
double top double-rule lines on top and bottom; single rule lines on the sides 
4.4 Procedure Draw 
There are two overloaded versions of procedure dxaw, the disambiguating parameter being kind or 
box_definition. The first version draws a few kinds of boxes using default box—drawing characters, 
the second version uses selected characters for each part of a box. 


4.4.1 Using Default Boxes 


The first version of procedure draw displays one of several pre-defined box types using default box—drawing 
characters. 
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procedure draw ( 


upper_left_row > row _range; 

upper_left_ column : column range; 
lower_right_row ; row range; 

lower_right_ column : column_range; 

kind : simple_kind := single_sided; 
attribute : display_attribute := ( 


foreground => white, 
background => black, 
blink => false 
); 
page : display page := 0 

); — 

Given the upper left and lower right coordinates, a box is drawn on the specified display page with the speci- 

fied style and attributes. 

This call is valid for text modes only. 

Invalid coordinates or attempting to exceed the current mode’s display size has unpredictable results. 

An example for drawing a single-sided box follows. 


-- draw a single-sided box at (row/col) 


=—— 5,5 mana 5 , 20 
—— | | 


! 
= 10, S---~-----~10, 20 


-- in page zero, with White/Black blinking attributes. 


with common_display types, 
box; 
use common_display types; 
procedure box testl is 
attr : display_attribute; 


begin 
attz.blink := true; 
box.draw ( 
upper_left row => 5, 
upper_left_colum => 5, 
lower_xright_row => 10, 
lower_right_column => 20, 
attribute => attr 
); 
end; 
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4.4.2 Using a Selected Character 


The second version of procedure draw uses a selected character to draw each box part. 
procedure draw ( 


upper_left_ row : row_range; 
upper_left_column : column_range; 
lower_right_row : row_range; 
lower_right_column : column _range; 
box_definition : user_definition; 
attribute : display _ attribute := ( 


foreground => white, 

background => black, 

blink => false 

); 

page : display page := 0 
); 
Given the upper left and lower right coordinates, a box is drawn with the specified character and attributes 
in the specified display page. 
This call is valid for text modes only. 
Invalid coordinates or attempting to exceed the current mode’s display size has unpredictable results. 
An example of procedure draw using a selected character follows. 

-- draw a box with the Happy Face character at (row/col) 


-- in page zero, with Cyan/Black attributes. 
with common display types, 
box; 
use common display types; 
procedure box test2 is 
attr : display attribute; 
my box : box.usex_definition := (others => 1); 
-- 1 = Happy Face 


begin 
attr.foreground := cyan; 
box.draw ( 
upper_left_ row => 5, 
upper_left_column => 5, 
lower right _row => 7, 
lower_right_column => 30, 
box_definition => my _ box, 
attribute => attr 
); 
end; 


Note that a different box—drawing character from the IBM PC character set may be used for each part. 
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Chapter 5 Package Common_Display Types 


The package common_display_ types contains type declarations for the various packages that handle 
display operations: box, cursor, tty, and video. 


SPECIFICATION 


package common_display types is 
subtype byte is integer range 0 .. 255; 
subtype extended_ascii is integer range 0 .. 255; 


subtype column range is integer range 0 .. 79; 
subtype row_range is integer range 0 .. 24; 


subtype cursor_size is integer range 0 .. 13; 
subtype display page is integer range 0 .. 7; 
type color is ( 


black, blue, green, 

cyan, red, magenta, 
brown, white, grey, 
light_blue, light green, light cyan, 


light _red, light_magenta, yellow, 

bright_white 

); 
subtype background_color is color range black .. white; 
type display attribute is 


record 
foreground : color := white; 
background : background color := black; 
blink : boolean := false; 


end record; 


—- underline valid for monochrome mode only. 
underline : constant display attribute := ( 
foreground => blue, 
background => black, 
blink => false 
); 
subtype color palette is integer range 0 .. 1; 
type graphic color is ( 
background, colori, 
color2, color3 
); 
end common display types; 
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Package cursor provides operations to move a text mode cursor, to get the current cursor coordinates, and 
to alter the visibility or form of the cursor. 


The Color/Graphics Adapter has eight display pages (0 .. 7). in 40 column by 25 line text modes and four 
display pages in the 80 column by 25 line text modes. The Monochrome adapter has only one display page. 
Specifying an invalid display page (i.e. a display page that is not defined for the current text display mode) 
has unpredictable results. 


SPECIFICATION 


with common display types; 
use common display types; 
package cursor is 
procedure set_size ( 
start line : cursor_size; 
end line =: cursor_size 
); 
procedure inhibit; 


procedure move ( 


xow > xow_range; 
column : column_range; 
page : display page := 0 


); 
procedure get position ( 


row ; out row range; 

column : out column_range; 

page : display page := 0 

); 
procedure up (page: display page := 0); 
procedure down. (page: display page := 0); 
procedure left (page: display_page := 0); 
procedure right (page: display page := 0); 


end cursor; 
6.1 Procedure Set_Size 


Procedure set_size sets the start_line and end_line of the blinking cursor. 


procedure set_size ( 
start_line : cursor_size; 
end line : cursor_size 
); 
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This call is valid only in Text modes. 
The ROM BIOS default values for start_line and end_line are: 


ae a 
a a a ae 
ae 


A particular text a mode is selectable via the procedure video. set. Refer to package video for a 
description of the various text modes. 


This call corresponds to Interrupt 16#10#, function 16#01#. 
6.2 Procedure Inhibit 


Procedure inhibit inhibits display of the cursor (i.e. makes it invisible). 
procedure inhibit; 

This call is valid only in Text modes. 

This call corresponds to Interrupt 16#10#, function 16#01#. 


6.3 Procedure Move 


~] 


He 


~] 


Procedure move moves the cursor to the specified row and column within the specified display page. 
procedure move ( 

row 2: 4xrow_range; 

colum : column_range; 

page : display page := 0 

); 

Moving the cursor to a location that is invalid for the current display mode has unpredictable results. 
The coordinate scheme is rectangular: 
(0,0) Coordinate (Row 0, Column 0) is the upper left comer of the display. 


(24,79) Coordinate (Row 24, Column 79) is the lower right comer of the display in 80-column 
text modes. 


This call corresponds to Interrupt 16#10#, function 16#02#. 
An example follows: 


-- Move the cursor to row 10, columm 20 in display page 
~~ 0 (default page). 


cursor.move (row => 10, colum => 20); 
6.4 Procedure Get_Position 


Procedure get_position retums the current cursor position for the specified display page. 
procedure get position ( 


row : out row_range; 
colum =: out column_range; 
page : display page := 0 


3 
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This call corresponds to Interrupt 16#10#, function 16#03#. 
An example follows. 
—— Get the current cursor position of display page 1 


cursor.get position ( 


zow => pagel_row, 
column => pagel_col, 
page => 1 


); 
6.5 Procedure Up 


Procedure up moves the cursor up one location in the specified display page. 
procedure up (page : display page := 0); 

Attempts to move the cursor up past the top of the screen are ignored. 

This call corresponds to Interrupt 16#10#, function 16#02#. 

An example follows. 
-- Move the display page zero cursor up one location. 


cursor .up; 


6.6 Procedure Down 


Procedure down moves the cursor down one location in the specified display page. 
procedure down (page : display page := 0); 

Attempts to move the cursor down past the bottom of the screen are ignored. 

This call corresponds to Interrupt 16#10#, function 16#02#. 

An example follows. | 


-~ Move the display page one cursor down one location. 


cursor.down (page => 1); 
6.7 Procedure Left 


Procedure left moves the cursor left one location in the specified display page. 
procedure left (page : display page := 0); 

Attempts to move the cursor left past the edge of the screen are ignored. 

This call corresponds to Interrupt 16#10#, function 16#02#. 


6.8 Procedure Right 


Procedure right moves the cursor right one location in the specified display page. 
procedure right (page : display page := 0); 

Attempts to move the cursor past the right edge of the screen are ignored. 

This call corresponds to-Interrupt 16#10#, function 16#02#. 
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Chapter 7 Package Directory 


Package dixectory provides subprograms that operate on directories. A program using this package 
can create or delete directories and can change the current directory of the program. 


SPECIFICATION 


with errors, 


disk types; 
package directory is 
subtype pathname is string (1 .. 


function make (name : in string) 
return errors .extended_ errors; 

function remove (name : in string) 
return errors.extended_errors; 


function change_to (name : in string) 
return errors .extended errors; 


procedure current_name ( 


for_drive : disk_types.drive_ designator; 
name : out pathname; 

last : out natural; 

error : out errors.extended_ errors 


); 
end directory; 


7.1 Function Make 


Function make creates a directory. 


function make (name : in string) retu 
errors .extended.errors; 


This call corresponds to Interrupt 16#21#, function 16#39#. 
Possible errors are: = 


errors.path_not found 


e errors.access_denied 


Examples which use function make follow. 


-- Create the directory TEST.DIR in the 
-~ of the ‘C’ Drive. 


with errors, 
directory; 


procedure dir testl is 


error : errors.extended errors; 
begin : seh 
error := directory.make (name => ”C:\TEST.DIR”) ; 


21 
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root directory 
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Another example follows. 


-- Create the directory TEST.DIR in the current directory 
—- on the default disk drive. 


with errors, 
dizrectory; 
procedure dir test2 is 
error : errors.extended_ errors; 


begin 
error := directory.make (name => “TEST.DIR”) ; 
end; 


7.2 Function Remove 


Function remove removes a directory. 


function remove (name : in string) return 
errors .extended_ errors; 


This call corresponds to Interrupt 16#21#, function 16#3A#. 
Possible errors are: | 

® errors.path_not_ found 

© errors.access_denied 

e errors. remove_current_directory 
An example which uses function remove follows. 


—-- Remove TEST.DIR from the current drive and directory. 
with directory, 
errors; 
procedure remove_test is 
error : errors .extended errors; 


begin 
error := directory.remove (name => "“TEST.DIR”) ; 
end; 


7.3. Function Change_To 


Changes the current directory for the program. 


function change to (name : in string) 
return errors.extended_errors; 


This call corresponds to Interrupt 16#21#, function 16#3B#. 
A possible error follows: 
¢ errors.path_not_found 
An example of using package directory with the function change_to follows. 
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-- Change the current working directory to the parent directory 
with directory, 
errors; 

procedure change_test is 

error : errors .extended errors; 
begin 

error := directory.change_to (name => ”.."); 
end; 


7.4 Procedure Current_Name 


Procedure current_name obtains the pathname of the current working directory for the specified drive. 


procedure current_name ( 
for_drive : disk _types.drive_designator; 


name : out pathname; 
last : out natural; 
error : out errors.extended_errors 


); 
The returned pathname does not include the drive identifier. 
The returned parameter last denotes the index of the last valid character position in narne. 
This call corresponds to Interrupt 16#21#, function 16#47#. 
A possible error follows: 
® errors.invalid drive 
An example of using package dixectory with procedure current_name follows. 
-- Get and display the current directory for the ’A’ drive. 


with directory, 
disk types, 
errors, 
text_io; 


use disk types, 
directory; 
procedure display dir is 


current _a dir. > pathname; 

last_valid char : natural; 

current_name_error : errors.extended errors; 
begin 


for_drive => a, 


name => current _a dir, 
last => last_valid_char, 
error => current_name error 


); 
text_io.put_line (current_a dir (1 .. last_valid_ char) ); 
end; 
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Chapter 8 Package Disk 


Package disk provides operations on disk devices. 
SPECIFICATION 


with disk types; 
package disk is 
procedure reset; 


function set_default (to_drive : disk_types.drive_id) 
return disk types.logical_drive_count; 


function get_default return disk_types.drive_id; 
— Get File Allocation Information 


procedure get_allocation_info ( 


for_drive : disk . types.drive designator; — 
sectors : out natural; 

bytes_per sector : out natural; 

clusters : out natural; 

fat_id byte : out disk types. identification; 
error : out boolean 


); 
procedure set_verification (is_on : boolean) ; 
function verification_is on return boolean; 
procedure get_free_space ( 

for_drive : disk_types.drive_ designator; 

sectors _per_cluster : out natural; 

available clusters : out natural; 


bytes_per_sector : out natural; 
total_clusters : out natural; 
error : out boolean 


); 
procedure get_free_space ( 


for_drive : disk types.drive designator; 
free_bytes : out long integer; 
total _ space =: out long integer; 
error : out boolean 
; 

end disk; 


8.1 Procedure Reset 


Procedure reset flushes all file buffers to disk without closing any files. 
procedure reset; 
This call corresponds to Interrupt 16#21#, function 16#0D#. 
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8.2 Function Set_Default 


Function set_default sets the current default drive and retums the number of logical drives installed. 


function set default (to drive : disk types.drive id) 
return disk types.logical drive count; 


Logical drive means any block device: ram disk, floppy disk, or hard disk. 

This call corresponds to Interrupt 16#21#, function 16#0E#. 

An example of using package disk with function set_default follows. 
-- set the current drive to the ‘A’ drive. 


with disk, disk types; 
use disk, disk types; 
procedure disk test1 is 

count : disk _types.logical drive_count; 
begin 

count :* set_default (to_drive => a); 
end; 


8.3 Function Get_Default 


Function get_default retums the drive ID of the default disk drive. 
function get_default return disk_types.drive_id; 
This call corresponds to Interrupt 16#21#, function 16#19#. 


8.4 Procedure Get_Allocation_Info 


Procedure get_allocation_in£o obtains information about the specified disk drive. 


procedure get_allocation_ info ( 
for_drive : disk_types.drive_ designator; 


sectors : out natural; 
bytes per sector : out natural; 
clusters : out natural; 
fat_id byte : out disk _types.identification; 
error : out boolean 


); 
This call corresponds to Interrupt 16#21#, function 16#1C#. 


8.5 Procedure Set_Verification 


Procedure set_verification tums on or off the read-after— write verification of all data written to disk. 
procedure set_verification (is_on : boolean) ; 

This call corresponds to Interrupt 16#21#, function 16#2E#. 

An example of using package disk with procedure set_verification follows. 
~~ set verification to on 


disk.set_verification (is_on => true); 
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8.6 Function Verification_Is On 


Function verification_is_on determines whether the read— after-write verification flag is on or off. 
function verification_is on return boolean; 
This call corresponds to Interrupt 16#21#, function 16#54#. 


8.7 Procedure Get_Free_Space 


Procedure get_free_space obtains selected information for ag specified disk drive. 


procedure get_free space ( 
for_drive : disk _types.drive _dasignater; 
sectors per cluster : out natural; 
available clusters : out natural; 


bytes_per_ sector : out natural; 
total_clusters : out natural; 
error : out boolean 


); 
An error may be caused by an invalid drive designator. 
This call corresponds to Interrupt 16#21#, function 16#36#. 
8.8 Procedure Get_Free_Space 


Procedure get_free_space obtains the amount of total space and amount of free space for the specified 
disk drive. 


procedure get_free space ( 


for_drive : disk _types.drive designator; 
free_bytes : out long integer; 
total_space =: out long integer; 

error : out boolean 


); 
An error may be caused by an invalid drive designator. 
This call corresponds to Interrupt 16#21#, function 16#36#. 
An example of using package disk with procedure get_free_space follows. 
~- Get and display the used space of the ‘A’ disk drive. 


with disk, 
text_io; 
use disk; 


procedure display used_on_a is 
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total_free : long_integer; 

disk size : long_integez; 

space_error : boolean; 

begin 

get_free_space ( 
for_ drive => a; 
free_byte => total free; 
total_space => disk_size; 
error => space_error 


if not space_error then 
text_io.put_line ( 
“Total Used is ” & 
long integer’ image (disk_size - total_free) ); 
end if; 
end; 
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This package contains type declarations used by the disk and directory operation packages abso- 
lute_disk, directory, and disk. 


SPECIFICATION 


package disk types is 
type drive designator is ( 
current drive, a, b, c, d, e, 
£, g, h, i, j, k, 1, m, 1, 0, 
P, qd, zx, 8, t, U, V, W, , Y, 
Zz 
; 
subtype drive id is drive designator range a .. 2; 


subtype logical drive count is integer range 0 .. 255; 
subtype identification is integer range 0 .. 255; 


end disk types; 
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Chapter 10 Package Equipment 


Package equipment provides a function that enumerates the system—recognized devices and facilities 
present on the machine. 


SPECIFICATION 


package equipment is 
type mode is (not_used, color40, color80, mono80) ; 


type equipment _list is 


record 

printers : integer; 
serial printer : boolean; 
game_adapter : boolean; 
48232_ports : integer; 
dma_present : boolean; 
diskette_drives : integer; 
initial video _mode : mode; 
system_ram : integer; 
math_coprocessor : boolean; 
diskette present =: boolean; 


end record; 
function list return equipment_list; 
end equipment ; 


10.1 Function List 


| Function List retums the list of currently installed equipment. 
function list return equipment list; 
The equipment_list information corresponds to the word at address 0000:0410H. 
This call corresponds to Interrupt 16#11#. 
An example of using package equipment with function List follows. 


—~ determine if a game adapter is present. 
with equipment; use equipment; 
procedure equipment _testl1 is 
my equipment : equipment list; 
begin : 

my equipment := equipment .list; 

if my_equipment .game_adapter then 

null; : 

end if; 

end; 
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Chapter 11 Package Errors 


Package errors provides PC-DOS status declarations and for version 3.0 or later of PC-DOS, a proce- 
dure to get extended status information. ; 


SPECIFICATION 


package errors is 


type extended_errors is ( 
ok, 
invalid function, 
file_not_found, 
path_not_found, 
no_handle available, 
access_denied, 
invalid handle, 
memory blocks destroyed, 
insufficient _memory, 
invalid memory block, 
invalid environment, . 
invalid format, 
invalid file acces s, 
invalid data, 
reservedlé, 
invalid drive, 
remove _current_ directory, 
not_same device, 
no_more files, 
disk write } protected, 
unknown_unit, 
drive not ready, 
command _not_defined, 
disk_data error, 
bad_structure_length, 
seek error, 
unknown_media type, 
sector not found, 
printer_outof_paper, 
write error, 
read_error, 

; general failure, 

file sharing violation , 
file_locking violation , 
invalid _disk change, 
no_fcb available, 
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file already_exists F 
reserved81, 
cannot_make, 
interrupt_: failure, 
unknown_error 


); 


type class_code is ( 
out_of resource, 
authorization, 
hardware_failure, 
application_error, 
bad_format, 
media error, 
unknown 
); 
type action code is ( 
try_again, 
user to ) Fix, 
shut _¢ down: immediate, 
retry | after: fix, 
); 


type locus_code is ( 
unknown, 
network_related, 
memory_related 
); 


-- DOS 3.0 procedure 


temporary_situation, 
internal_dos_error, 
system_sw_error, 
not_found, 

item locked, 

already exists, 


try_again_ later, 
shut_down program, 
ignore_error, 
unknown 


block_device 7 
serial device . 


procedure get ¢ extended_info ( 


error : out extended _« errors; 
class : out class_code; 
action : out action_code; 
locus : out locus_code 


); 


end errors; 


11.1 Procedure Get_Extended_Info 


Procedure get_extended_info obtains detailed information after a previously unsuccessful system 
call. The information may suggest action that the program should take. 


procedure get_ extended _ info ( 


error out extended_errors; 
class : out class_code; 
action : out action_code; 
locus : out locus_code 


); 


This function requires DOS 3.0 or higher. Execution of this function with a lower revision causes the excep- 
tion revision. incorrect_dos_versionto be raised. 


DOS Environment Library User’s Guide 


34 


sy 


Package errors 


This call corresponds to Interrupt 16#21#, function 16#59#. 
An example follows. 
with errors, 
directory; 
use errors; 
procedure errors testl is 


make_error : extended_errors; 


error : extended_errors; 
class : class_code; 
action : action_code; 
locus : locus_code; 
begin 


make_error := directory.make (name => “A:\Junk”); 
if make_error /= ok then 
get_extended info (error, class, action, locus) ; 
end if; 
end; 
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Package file io provides file input—output, file attribute manipulation, and wildcard search operations. 
Note that most of the essential input~output facilities provided in this package are available in a largely sys- 
tem—independent standard package, text_io, which is distributed with the Meridian Ada compiler. 


Be aware that the Ada predefined type character supports only seven—bit ASCII characters. If it is 
necessary to manipulate all eight bits of a byte, then pragma suppress should be used when using objects 
of type character (to avoid the exception constraint_error), or a different type altogether (e.g. 
Common_display types.extended_ascii) should be used. 


SPECIFICATION 


with errors, 
time, 
system; 


package file io is 
type file handle is new integer; 
-- Standard I/O Handles 


stdin : constant file handle := 0; -- CoN 
_ stdout =: constant file handle := 1; -- con 
stderr : constant file handle := 2; -- CoN 
stdaux =: constant file handle := 3; -- AUX 
stdlist : constant file handle := 4; -— PRN 


type file attribute types is ( 
xead_only, hidden, system, 
volume_label, subdirectory, archive 

); 


type file attributes is array (file_attribute_types) 
of boolean; 


~- Access Code Values 
type access_mode is ( 

read_only, 

write only, 

read_write 

); 

type sharing mode is ( 
compatibility, deny read_write, deny write, 
deny read, deny none 


; 
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type 


access code is 


record 
inheritance flag : boolean := true; 
-- DOS 3.0 only 


sharing 


; sharing_mode := compatibility; 


-- DOS 3.0 only 
reserved bit 
-— DOS 3.0 only 


: boolean :z false; 


file access_mode : access_mode := xread_write; 
end record; 


type standard_io is (input, output); 


type method_code is ( 


); 


beginning, 


current_location, 
current_end 


subtype timestamp_data is time.packet; 


type transfer_data is limited private; 


type file data 


record 


name 
attributes 
timestamp 
file_size 


end record; 


procedure create 


); 


name 
handle 
error 
attributes 


— DOS 3.0 
procedure create_temporary ( 


pathname 
handle 
temp file 
last 
error 
attributes 


); 


string (1. .12); 

file attributes; 
timestamp_data; 
long_integer; =~ in bytes 


( 
string; 
out file_handle; 
out errors.extended_errors; 
file attributes := 
(others => false) 


string; 
out file_handle; 


: out string; 
: out natural; 
: out errors.extended_errors; 


file attributes := 
(others => false) 
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-- DOS 3.0 
procedure ceace pe eriai rp! ( 
handle out file handle; 
temp file : out string; 
last : out natural; 
error : out errors. extended | errors; 


attributes : file } attributes := 
j (others => false) 
he 


-- DOS 3.0 
procedure create_new ( 
name : string; 
handle : out file handle; 
error _ $ out errors.extended_errors; 


attributes : file attributes := 
(others => false) 
); 
procedure open ( 


name : string; 

handle : out file handle; 

error =: out errors.extended_errors; 

code : access_code := ( 
inheritance_flag => true, 
sharing => compatibility, 
reserved bit => false, 


file_access_mode => read_write | 


); 
function close (handle : file handle) 
return errors.extended_errors; 


function cooked (for_standard : standard |_io) 
return errors .extended | errors; 

function raw (for_: standard : standard _io) 
return errors.extended | errors; 


procedure read ( 


handle : £ile handle; 

bytes_to read : natural; 

buffer_address : system. address; 
bytes_read : out natural; 

error > out errors.extended_errors 


); 
procedure write ( 

handle 7 file_handle; 
bytes _to write : natural; 
buffer_address : system. address; 
bytes_written out natural; 
error out errors.extended | errors 

); 
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function delete (name : string) return 
errors .extended_errors; 


function rename ( 


old_name : string; 
new name : string 
) return errors.extended_errors; 


procedure move file _ pointer ( 
: £ile_handle; 


handle 
offset_mathod 
offset_value 
new_pointer 
error 


: mathod_code; 


long_integez; 
out long integer; 
out errors.extended_errors 


-- Get and Set File Attributes 


procedure get_attributes ( 


name : string; 
attributes : out file attributes; 
error 2 out errors .extended_errors 


); 


function set_attr 


ibutes ( 


name : stzring; 
attributes : file_attributes 
) veturn errors.extended_errors; 


—— Get and Set File Date and Time 


function set_file time ( 
handle : file handle; 
time : timestamp_data 
) return errors.extended_errors; 


procedure get file time ( 


handle : file_handle; 
time : out timestamp_data; 
error : out errors .extended_ errors 


); 


procedure dup_filehandle ( 


handle : 
new_handle : 
error : 


); 


file handle; 
out file_handle; 
out errors .extended_errors 


procedure cdup_filehandle ( 


handlel : 
handle2 : 
error : 


); 


: £ile_handle; 
file handle; 
out errors .extended_errors 
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-~- File Search functions 


procedure find first ( 


name, template. ; string; 

transfer area ; out transfer data; 

file info : out file _ data; 

error : out errors.extended | errors; 


search attributes: file ) attributes := 
(others => false) 


); 


procedure find next ( 
transfer_area : in out transfer data; 


file_info : out file data; 
error : out errors.extended_errors | 
); 
private 
type transfer data is array (0 .. 21) of integez; 
end file io; 


12.1 Procedure Create 


Procedure create creates a file in the current or specified directory, and opens it for program use. | 
procedure create ( 


name : string; 
handle : out file handle; 
error : out errors.extended_errors; 


attributes : file attributes := 
(others => false) 
); 

If the file already exists, then it is truncated to zero. The file is opened for read/write access. 
File attributes volume and subdirectory are ignored by this call. 
This call corresponds to Interrupt 16#21#, function 16#3C#. 
Possible errors are: 

® errors.path_not_found 

® errors.no_handle available 

© errors.access_denied 
An example of using package £ile_io with procedure create follows. 


~~ create “Test .Out” with normal attributes in the 
—~ current directory on the default drive. 

with file_io, errors, text_io; 

use file io, errors; 

procedure fio testl is | 
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test_handle : file handle; 
create_error : errors extended errors; 
begin 
create ("Test .Out”, test_handle, create_error) ; 
if create_error = ok then 
— use test_handle for any read or write requests. 
null; 
else 
text_io.put_line ( 
"Error on Create !! : " & 
errors .extended_errors ‘image (create_error) 


12.2 Procedure Create_Temporary 


There are two overloaded versions of procedure create_temporary disambiguated by the presence 
or absence of the parameter pathname. The first version creates atemporary file in the directory specified 
by the pathname; the second version creates a temporary file in the current directory. 


12.2.1 Using Pathname 


With a pathname parameter, procedure create_temporary creates a temporary file in the directory 
specified by pathname, and opens the file. 


-- DOS 3.0 
procedure create_temporary ( 
pathname : string; 
handle : out file_handle; 
temp file : out string; 
last : out natural; 
error : out errors.extended_errors; 


attributes : file_attributes := 
(others => false) 
); 


The parameter temp_file is set to the path and name of the temporary file. Parameter /ast is the index position 
of the last valid character of the temp_file string. 


The temporary file is not automatically deleted at program completion. 
The file is opened for read/write access. 
File attributes volume and subdirectory are ignored by this call. 


This function requires DOS 3.0 or higher. Execution of this function with a lower revision causes the excep- 
tion revision. incorrect_dos_version to be raised. 


This call corresponds to Interrupt 16#21#, function 16#5A#. 
Possible errors are: 
¢ errors.path_not_found 


e errors.access_denied 


DOS Environment Library User’s Guide 42 


Package file_io 


An example of using package file _io with procedure create )_ temporary follows. | 


~~ Create a temporary file in the directory specified 
-- by "A: \TEMP.DIR” (a: \temp.dir must already oe 


with file io, errors; 
use file io; 
procedure fio test2 is 


temp_handle =: file handle; 

temp filename : string; 

last_char : natural; 

create error : errors .extended_errors; 
begin 


create_temporary ( 
pathname => “A:\TEMP.DIR”, 


handle => temp handle, 
temp file => temp_filename, 
last => last char, 
error => create error 


ds 
end; 


12.2.2 Using the Current Directory 


Without a pathname parameter, procedure create )_ temporary creates a temporary file in the current 
directory on the default disk drive and opens the file. a 


-~ DOS 3.0 
procedure create temporary ( 
handle : out file handle; 
temp file : out string; 
last : out natural; 
error >: out errors .extended_errors; 


attributes : file attributes := 
. (others => false) 
); 


The parameter temp_file is set to the name of the temporary file. Parameter /ast is the index position of the 
last valid character of the temp_file string. 


The temporary file is not automatically deleted at program completion. 
The file is opened for read/write access. 
File attributes volume and subdirectory are ignored by this call. 


This function requires DOS 3.0 or higher. Execution of this function with a lower revision causes the excep- 
tion revision. incorrect __dos_version to be raised. 


This call corresponds to Interrupt 16#21#, function 16H#SA#. 
Possible errors are: 
® errors.path_not_found 7“ 


® errors.access denied 
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12.3 Procedure Create_New - | a 


Procedure create_new creales a file in the current or specified directory, and opens the file. If the file al- 
ready exists, then the file already_exists cor is returned. 


-- Dos 3.0 


procedure create _new ( 


name : 
handle 7 
error : 
attributes : 


); 


string; 
out file handle; 
out exrors.extended_errors; 
file attributes := 
(others => false) 


The file is opened for read/write access. 


File attributes volume and subdizectory are ignored by this call. 


This call corresponds to Interrupt 16#21#, function 16#5B#. 


This function requires DOS 3.0 or higher. Execution of this function with a lower revision causes the excep- 
tion revision. incorrect_dos_version to be raised. 


Possible errors are: 


e errors.path_not_found 


e errors.no_handle_ available 2) 


¢ errors.access_denied 


e errors.file_already_exists 


An example of using package file_io with procedure create_new follows. 


-- Create “TEST” as a Read_Only file in the current 


-- directory. 


with file_io, errors, 


use file io; 


procedure fio test3 is 


new_handle 
create error 
file_attr 


begin 


: £ile_handle; 

: errors.extended_errors; 

: file_attributes := 
(others => false); 


file attr (read_only) := true; 


create_new ( 
name 
handle 
error 


=> “Test”, 
=> new handle, 
=> create error, 


attributes => file_attr 
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12.4 Procedure Open 


Procedure open opens an existing file. 
procedure open ( 
name : string; 
handle : out file handle; 
error : out errors.extended_errors; 
code =: access_code := ( 
inheritance flag => true, 
sharing => compatibility, 
reserved bit => false, 
file_access_mode => read write 
) 
); 


For DOS revision 2, the file_access_mode is the only parameter actually used; the parameters inheri- 
tance_flag and sharing are ignored. All the parameters are used in revision 3.0 and higher. 


Normal files and files with the system and hidden : ttributes can be opened with this call. 
This call corresponds to Interrupt 16#21#, scion 
Possible errors are: 
® errors.invalid function 
e errors.file not_found 
° errors.path_not_found 
* errors.no_handle available 
° errors.access_denied 
® errors.invalid file access 
An example of using package f£ile_io with procedure open follows. 


—~ Open the file "“TEST.OUT” in the current directory with 
~~ the default settings. 

with file_io, errors; 

use file io; 

procedure fio test4 is 


test_handle : file handle; 


open_error : errors.extended_errors; 
begin 

open ("Test .Out”, test_handle, open_error) ; 
end; 


12.5 Function Close 


Function close closes a file whose handle was previously returned by a successful call to open, create, 
Create_temporary, or create_new. 


function close (handle : file handle) 
return errors. extended_errors 7 
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Closing flushes the file’s internal buffers to disk and releases the handle for reuse. 
The file’s date and time is updated if the file was modified. eo) 
This call corresponds to Interrupt 16#21#, function 16#3E#. 
A possible error follows. 
e errors.invalid_handle 
An example follows. 


—— Close the file associated with the specified handle 
-- and notify user if in error. 


with file io, errors; 
use file_io, errors; 
procedure fio tests (test_handle : file handle) is 
begin 

if close (handle => test_handie) /= ok then 

text_io.put_line ("Error on Close”); 

end if; 

end; 


12.6 Function Cooked 
Function cooked sets the cooked bit in the device driver information word for the specified standard de- 
vice. 

function cooked (for_standard : standard _io) 

return errors.extended_errors; % 

Characters that require special action are checked on input or output. 
Character devices perform their input and output in the cooked mode by default. 
This call corresponds to Interrupt 16#21#, function 16#44#. 


12.7 Function Raw 


Function zaw sets the raw bit in the device driver information word for the specified standard device. 
function raw (for_standard : standard _io) 
return errors.extended_errors; 


Checking for Control-C (4C) or any other control characters is tumed off. This increases display speed. 
The system does not take any action on special characters in the input stream. 


This call corresponds to Interrupt 16#21#, function 16#44#. 
12.8 Procedure Read 


Procedure read reads from a file or device associated with the specified handle. 


procedure read ( 
handle : file_handle; 
bytes _to_read : natural; 
buffer_address : system. address; 
bytes_read : out natural; 
error : out errors.extended_errors “ 
); 


DOS Environment Library User’s Guide 46 


Package file_io 


The number of bytes actually read is retumed in bytes_read. This value may be less than the value 
specified in bytes _to_read if: 


® anerror occurs. 
e the end of file is encountered. 


¢ an end-of-line sequence (carriage-retum/line-feed) is read from a character de- 
vice that is in cooked mode. The CR/LF pair is read into the buffer and is counted. 


The read buffer associated with the buffer_address must be large enough for the number of bytes specified 
for reading. 


The file position pointer is updated. 
This call corresponds to Interrupt 16#21#, function 16#3F#. 
Possible errors are: 


° errors.access_denied 
° errors.invalid handle 
An example of using package £ile_io with procedure read follows. 


~~ Read a maximum of 80 bytes or until a carriage-return 
~- is detected from the standard input device. 

with file io, errors; 

procedure fio test6 is 


buffer : string (1 .. 80); 
qty read : natural; 
read_error =: errors.extended_errors; 
begin 
file_io.read ( 
handle => stdin, 


bytes to read => 80, 
buffer address => buffer (1)’ address, 
bytes read => qty read, 
error => read_error 
); 
end; 


12.9 Procedure Write 


Procedure write writes to a file or device associated with the specified handle. 


procedure write ( 
handle : £ile_ handle; 
bytes_to write : natural; 
buffer_address : system. address; 
bytes _written : out natural; 
error ; out errors.extended_errors 
); 
The number of bytes actually written is retumed in bytes_written. This value may be less than the 
number specified in bytes_to_write if an error occurs (e.g. the disk is full). 
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The file position pointer is updated. 
This call corresponds to Interrupt 16#21#, function 16#40#. “~ 
Possible errors are: 
e errors.access_denied 
e errors.invalid _handle 
An example of using package £ile_io with procedure write follows. 
~- Write the test string to a previously-opened file. 


with file io, errors; 
use file io; 
procedure fio _test7 (open_handle : file handle) is 


qty_written : natural; 


buffer : string (1 .. 14) :2 "This is a Test”; 
write_error : errors.extended_errors; 
begin 
write ( 
handle => open_handle, 


bytes _to write => buffer’ length, 
buffer_address => buffer (1)' address, 
bytes_written => qty written, 

error => write_error 


); 
end; >) 
12.10 Function Delete 


Function delete deletes a file. 
function delete (name : string) return errors .extended errors; 
Wildcard characters are not valid. 
Files that have the read_only attribute set can not be deleted until cleared by a call to set_attributes. 
This call corresponds to Interrupt 16#21#, function 16#41#. 
Possible errors are: 
e errors.file_not_found 


° errors. access_denied 
12.11 Function Rename 


Function rename renames a file or moves the directory entry of a file to another directory. 


function rename ( 
old_name : string; 
new_name : string 
) return errors.extended_errors; 


Wildcard characters are not valid. ) 
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This call corresponds to Interrupt 16#21#, function 16#56#. 
Possible errors are: 


° erzrors.file not_found 
® errors. path_not_ found 
° errors.access_ denied 
° errors.not_same device 
An example of using package £ile_io with function rename follows. 


~~ Move "file.dat” to directory "test2” and rename 
-- it to "old.dat”. 

with file_io, errors; 

use file io; 

procedure fio test8 is 


rename_error : errors.extended errors; 


begin 
rename_error := 
rename ( 
old_name => "C:\TEST.DIR\FILE .DAT” ' 
new _ name => ”C:\TEST2.DIR\OLD.DAT” 
); 
end; 


12.12 Procedure Move_File_Pointer 


Procedure move_file ) pointer sets the file position for the next input—output operation. The position 
may be set to the start of the file, to the end of the file, or to a location relative to the current file position. 
procedure move file pointer ( 
handle : £ile_ handle; 
offset_meathod : method_code; 
offset_value =: long integer; 
new_pointer : out long integer; 
error : out errors .extended_errors 
); 
The value retumed in new_pointer is the byte offset from the beginning of the file. 
It is possible to set the file pointer to a location before the start of the file. If this is done, any 
attempt to read or write to the file causes an error. If the file pointer is positioned beyond the end 
of the file, a subsequent write to the file inserts “padding” (garbage characters) between the previous end of 
file and the selected file position. 
This call corresponds to Interrupt 16#21#, function 16#42#. 
Possible errors are: 
° errors.invalid function 
° errors.invalid handle 


An example of using package £ile_io with procedure move file pointer follows. 
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~~ Move the file pointer to the end of the file, 
-- and display that position. ) 


with file io, errors, text_io; 
use file_io; 
procedure fio _test9 (open_handle : in file handle) is 


current_end : method_code; 
file_size =: long_integer; 
move_error : errors .extended_errors; 
begin 
move_file pointer ( 
handle => open_handle, 


offset_mathod => current_end, 
offset value => 0, 
new pointer => file size, 
error => move_error 
); 
text_io.put_line (long_integer’ image (file_size)); 
end; 


12.13 Procedure Get_Attributes 


Procedure get_attributes obtains the attributes of a file in the current or specified directory. 
procedure get_attributes ( 


name : string; -) 
attributes : out file_attributes; c 


error : out errors.extended_errors 


); 


This call corresponds to Interrupt 16#21%#, function 16#43#. 
Possible errors are: 
e errors. file_not_found 
°¢ errors.path_not_found 
An example of using package £ile_io with procedure get_attributes follows. 
-- Determine if the Read_Attribute is set for the file "TEST.DAT”. 


with file_io, errors; 
use file_io, errors; 
procedure fio _test10 is 
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attr : file_io.file attributes; 
error : errors .extended_errors; 
begin 
get_attributes ("TEST.DAT”, attr, error); 
if error = ok and then attr (read_only) then 
~~ user defined. 
null; 
end if; 
end; 


12.14 Function Set_Attributes 


Function set_attributes sets the attributes on a file in the current of specified directory. 


function set_attributes ( 
name : string; 
attributes : file attributes 
) return errors.extended_errors; | 


The volume_label and subdirectory attributes cannot be set. 
This call corresponds to Interrupt 16#21#, function 16#43#. 
Possible errors are: 

® errors. file not found 


° errors.path_not_found 


° errors.access_denied 
12.15 Function Set_File_Time 


Function set_f£ile time modifies the time and date of a file associated with a specified handle. 


function set_file time ( 
handle : file handle; 
time : timestamp data 
) xeturn errors. extended _ errors; 


This call corresponds to Interrupt 16#21#, function 16#57#. 
A possible error follows. 


© errors. invalid handle 
12.16 Procedure Get_File_Time 


Procedure get_file time obtains the time and date of a file associated with a specified handle. 


procedure get_file time ( 
handle : file handle; 
time : out timestamp data; 
error : out errors .extended_errors 
); 


This call corresponds to Interrupt 16#21#, function 16#57#. 
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A possible error follows. 
e errors.invalid_handle 


12.17 Procedure Dup_FileHandle 


Procedure dup_filehandle duplicates a currently open handle. 
procedure dup_filehandle ( 


handle ; file_handle; 
new_handle : out file handle; 
error : out errors.extended_errors 


); 
The new_handle refers to the same file or device at the same position as the original handle. 
If the file position pointer is moved by one handle, the other handle is also moved. 
This call corresponds to Interrupt 16#21#, function 16#45#. 
Possible errors are: 
e errors. no_handle_available 


© errors.invalid_handle 


12.18 Procedure Cdup_FileHandle 


Procedure cdup_filehandle duplicates a file handle. 
procedure edup_filehandle ( 
handlel : £ile_handle; 
handle2 ; file handle; 
error : out errors.extended_errors 
): 
Handle2 is made to refer to the same file or device as handle!. 
A file previously associated with handle2 is closed if the file was open. 
If the file position pointer is moved by one handle, the other handle is also moved. 
This call corresponds to Interrupt 16#21#, function 16#46#. 
Possible errors are: 
e errors. no_handle_available 


® errors. invalid_handle 
12.19 Procedure Find_First 


Procedure find first finds the first occurrence of name_template with the specified attributes in 
the current or specified directory. 


procedure find first ( 


name_template : string; 

transfer_area : out transfer_data; 
file_info : out file_data; 

error - out errors.extended_errors; 


search attributes : file attributes :™ 
(others => false) 
; 
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Name_template may contain wildcard characters. 


If search_attributes contains volume_label, then only volume_label files are found. Other files 
are found if search_attributes specifies attribute combinations not including volume_label. 


This call corresponds to Interrupt 16#21#, function 16#4E#. 
Possible errors are: 

e errors.path_not_found 

e errors.no_ files 
For an example see procedure £ind_next. 


12.20 Procedure Find_Next 


Procedure find next finds the next occurrence of the name_template specified in the call to 
find first. 
procedure find _next ( 

transfer_area : in out transfer_data; 

file _info : out file data; 

error : out errors.extended_errors 

); 
Transfer_area must contain the information set there by a previous call to find_f£irst or £find_next. 
A possible error follows. 
e errors.no_more_ files 

An example of using package £ile_io with procedure find_next follows. 


-- General routine to display files on disk. 
with file io, errors, text_io; 

use file_io, errors; 

procedure display files (template : string) is 


search data : transfer_data; 

file information : file data; 

find error : exrrors.extended_errors; 
begin 


find first ( 
name_template => template, 
transfer_area => search_data, 
file info => file information, 
error => find error 
); 
if find_error = ok then 
text _io.put_line (file_information.name) ; 


Loop 
find next ( 
transfer_area => search data, 
file_info => file information, 
error => find _error 
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if find_error = ok then 
text_io.put_line (file information.name) ; 

else 
exit; 

end if; 

end loop; 
end if; 
end; 
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Package interxupt allows calls to the interrupt vectors. Referto your technical reference manuals for com- 
plete details of these interrupts and the required parameters. 


SPECIFICATION 


package interrupt is 


type interrupt_range is 
new integer range 0 .. 16#£f#; 


type registers is 


| record 
ax =: integer; 
bx  : integer; 
cx : integer; 
dx : integer; 
ds : integer; 
es : integer; 
si : integer; 
di : integer; 
carry : integer; -- 0 orl 


flags : integer; 
end record; 
procedure vector ( 
on : dnterrupt_range; 
register_block : in out registers 
); 
end interrupt; 


13.1 Procedure Vector 


Procedure vector takes an interrupt number and a list of register values. It performs the specified 
interrupt and retums the states of the registers following the interrupt. The CS, SS, SP, and BP registers may 
not be changed through this call. 


procedure vector ( 
on : interrupt_range; 


register_block : in out registers 
); 
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Only those registers actually used by the i interrupt need to be set. The flags component of the registers record 
is arranged as: =: 


we 
PF 
undefined 


AF | IOPL* 

undefined NT* 
ZF undefined 
SF 


#80286 flag 


Note that the carry flag is provided separately, since itis the flag most often used to indicate retum status 
in DOS calls. 


Warning: Incorrect use of any interrupt may have unpredictable or disasterous results. 
An example of using package interrupt with procedure vector follows. 


with interrupt; use interrupt; 
procedure outchar(c: character) is 
reg _ file: registers; 
begin 
reg _file.ax := 16#0200#; 
~- Note: Sets AH = 2. DOS function for Character Output. 
reg_file.dx := character’ pos (c) ; 
vector ( 
on => 16#21#, —- DOS interrupt 
xregister_block => reg file 
); 
end outchar; 


This example shows how to use interrupt .vector to calla DOS function. Note that this particular 
DOS call is also available as tty . put. 
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Chapter 14 Package Memory 


Package memory provides functions to allocate and deallocate memory. Functions are also present 
to manipulate allocated memory areas and to obtain information about available memory resources. 


Note that paragraphs are 16-byte quantities. 
SPECIFICATION 


with system, 
errors; 


package memory is 


type memory segment is new integer; 
type segment _offset is new integer; 


function make ( 
segment : memory segment; 
offset =: segment_offset 
) xeturn system. address; 


procedure split ( 
dos_address : system.address; 
segment : out. memory segment; 
offset : out segment_offset 
); 


procedure allocate ( 
paragraphs_requested : natural; 


segment : out memory _segment; 
largest _block_avail : out natural; 
error : out errors .extended_errors 


); 


function release (segment : memory_segment) 
return errors.extended_ errors; 


procedure modify ( 
paragraphs_requested : natural; 


segment : memory segment ; 
largest_block_avail : out natural; 
error : out errors .extended_errors 
); 
function installed return integer; -- in K-bytes 
function used return natural; -——- in Paragraphs 
end memory; 
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14.1 Function Make 


Function make retums an address from the specified segment and offset. 


function make ( 
segment : memory segment; 
offset : segment_offset 
) xreturn system. address; 


This does not correspond to a particular DOS function. 
14.2 Procedure Split 


Procedure split obtains the segment and offset from a dos_address. 


procedure split ( 
dos_ address : system.address; 
segment : Out memory segment; 
offset : out segment offset 
); 


This does not correspond to a particular DOS function. 
14.3. Procedure Allocate 


Procedure allocate dynamically allocates memory of the number of paragraphs_requested and te- 
tums the segment paragraph of the allocated memory block. 


procedure allocate ( 
paragraphs_requested : natural; 


segment : out memory segment; 
largest_block_avail : out natural; 
error : out errors.extended_errors 


); 


If the procedure fails to allocate the amount of memory requested, then /argest_block_avail contains the size 
of the largest available memory block. 


A paragraph is 16 bytes in size. 
This call corresponds to Interrupt 16#21#, function 16#48#. 
Possible errors are: 
© errors.memory blocks destroyed 
© errors.insufficient_memory 
An example of using package memory with procedure allocate follows. 
-“~ Allocate a block of 64k 


with memory, errors, system, tty; 
use memory, errors; 
procedure allocate_64k is 
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block_segment ; memory_segment; 
biggest_block : natural; 
allocate_error =: errors.extended_errors; 
starting address : system. address; 
begin 
allocate ( 
paragraphs_requested => 4096, 
segment => block_segment, 
largest_block_avail => biggest_block, 
error => allocate_error 


); 
if allocate_error = ok then 
starting address := 
make ( 
segment => block segment, 
offset => 0 
); 
else 
tty.put ("Error is : ” & 
errors .extended_errors’ image (allocate_erzror) ) ; 
end if; 
end; 


14.4 Function Release 


Function release releases a memory block that was previously allocated by allocate. 


function release (segment : memory segment ) 
return errors.extended_errors; 


The segment to release must be the same as the segment obtained from allocate. An attempt to release 
an invalid segment has unpredictable results. 


This call corresponds to Interrupt 16#21#, function 16#49#. 
Possible errors are: 
¢ exrrors.memory_blocks_destroyed 


e errors.invalid_memory_block 
14.5 Procedure Modify 


Procedure modify dynamically increases or decreases the size of a memory block that was previously 
allocated by allocate. 


procedure modify ( 
paragraphs_requested : natural; 


segment : memory segment; 
largest_block_avail : out natural; 
error : out errors.extended_errors 


); 


If the procedure fails to modify the size of the specified segment, then largest_block_avail contains the 
size of the largest available block. 
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This call corresponds to Interrupt 16#21#, function 16#4A#. 
Possible errors are: 

® errors. memory blocks destroyed 

° errors.insufficient_memory 

° errors.invalid memory block 


14.6 Function Installed 


Function installed retums the number of kilobytes of memory currently installed. 
function installed return integer; -- in K-bytes 

This call corresponds to Interrupt 16#12#. 

An example of using package memory with function installed follows. 
~- get the total installed memory. 


with memory, tty; 
procedure show total is 


begin . 
tty.put ("Total Memory is : ” & 
integer’image (memory. installed) ) ; 
end; 


14.7 Function Used 
Function used returns the size of the program at startup, excluding memory allocated during the program’s 
execution. : 
function used return natural; -— in Paragraphs 
The value retumed is in terms of paragraphs. 
The value retumed can be used with program_control.resident_quit. 


Information about the amount of memory used is obtained from the Program Segment Prefix; there is 
no corresponding system or BIOS call. 
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SPECIFICATION 


package port is 


function in_word (poxt_number : integer) 
return integer; 

function in_byte (port_number : integer) 
return integer; 


procedure out word ( 
port_number : integer; 
data : integer 
); 
procedure out_byte ( 
port_number : integer; 
data : integer 


); 
end port; 


USAGE 


Package port allows byte or word input and output to the specified port. 


Since the actual devices corresponding to particular 80x86 I/O ports may vary from machine to machine, 
you should consult the hardware reference materials or BIOS listing for your system in order to find out, for 
example, which I/O port corresponds to a serial chip or a speaker. 


The document describing the hardware and BIOS for the IBM PC/AT is: Personal Computer AT Technical 
Reference, IBM document number 6280070. 
15.1 Function In_Word 


Function in_word transfers a word from the specified input port. 


function in_word (port_number : integer) 
return integer; 


This does not correspond to a particular DOS function; it uses the 80x86 IN instruction. 
15.2 Function In_Byte 


Function in_byte transfers a byte from the specified input port. 


function in_byte (port_number : integer) 
return integer; 


This does not correspond to a particular DOS function; it uses the 80x86 IN instruction. 
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15.3. Procedure Out_Word 


procedure out_word transfers a word to the specified output port. 


procedure out_word ( 
port_number : integer; 
data : integer 
); 


This does not correspond to a particular DOS function; it uses the 80x86 OUT instruction. 
15.4 Procedure Out_Byte 


Procedure out_byte transfers a byte to the specified output port. 


procedure out_byte ( 
port_number : integer; 
data : integer 
); 
This does not correspond to a particular DOS function; it uses the 80x86 OUT instruction. 
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Package program_control provides functions that exert control over the executing program, that 
execute other programs, or that obtain information about resident programs. 


SPECIFICATION | 


with errors, 
memory; 


package program_control is 
subtype byte is integer range 0 .. 255; 
type program_end is ( 
voluntary end, ctrl_break_end, 
device_error, stay_resident_end 
); 
type state_type is (off, on); 
procedure quit (return_code : byte); 
function resident quit ( 
return_code : byte; 
xeserve_paragraphs : natural 
) return errors.extended_errors; 


procedure get return_code ( 
return_code : out byte; 
how_ended : out program_end 
); 
function break_status return state_type; 
procedure set_break_status (to_state : state_type); 
function segment_prefix return memory .memory_ segment; 
function execute ( 
program_name : string; 
command_arguments : string 
) return errors.extended_errors; 


| function msdos (command line : string) 
return errors.extended_errors; 


procedure get_environment_variable ( 
variable name : string; 
value : out string; 
last ; out natural 
); 


end program_control; 
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16.1 Procedure Quit 
Procedure quit terminates the calling program and retums connor. to PC-DOS or the parent program, 
yielding a return_code. 

procedure quit (return_code : byte); 


The return code can be examined with the batch command errorlevel or by the parent program 
using get_return_code. 


This call corresponds to Interrupt 16#21#, function 16#4C#. 
16.2 Function Resident. Quit 
Function resident_quit terminates the calling program without releasing its memory. Control retums 


back to PC- DOS or the parent program, yielding a retum code. 


function resident_quit ( 
return_code : byte; 
reserve _paragraphs : natural 
) return errors .extended | errors; 


Reserve_paragraphs is the number of 16 byte units that are to remain resident. An appropriate value to 
use for reserve_paragraphs may be obtained by using the function memory . used. 


This call corresponds to Interrupt 16#21#, function 16#31#. 
16.3 Procedure Get_ Return_Code 
Procedure get_return_code obtains the retum code of a child program after successful completion 


of the execute procedure. 


procedure get_return_code ( 
return_code : out byte; 
how_ended : out program_end 
); 
The return code can be obtained only once using this call. 
This call corresponds to Interrupt 16##21#, function 16#4D#. 


16.4 Function Break_Status 


Function break_status determines the current state of the operating system's Ctrl-Break checking flag. 
function break_status return state_type; 

This call corresponds to Interrupt 16#21#, function 16#33#. 

16.5 Procedure Set_Break_Status 


Procedure set_break_status sets the current state of the operating system’s Ctrl—Break checking flag. 
procedure set_break_status (to_state : state_type) ; 

This call corresponds to Interrupt 16#21#, function 164334. 

16.6 Function Segment_Prefix 


Function segment_prefix returns the memory segment of the calling program’s program segment prefix 
(PSP). 

function segment_prefix return memory.memory_ segment ; 
This does not correspond to a particular DOS function. 
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16.7 Function Execute 


Function execute executes the program with the specified program_name, passing the specified com- 
mand_argumentsto the program. The calling program is suspended during execution of the child program. 


function execute ( 
program_name : string; 
command_arguments =: string 
) return errors.extended_errors; 


Upon completion of the child program, control returns back to the calling program. It is then possible 
to determine how the child ended by calling the get_return_code procedure. 


This call corresponds to Interrupt 16#21#, function 16#4B#. 
Possible errors are: 

e errors.file_not_found 

e errors.access_ denied 

e errors.insufficient_memory 

® errors.invalid_set_strings 


e errors.invalid_ format 


16.8 Function Msdos 


Function msdos executes the PC-DOS command line interpreter with the specified command line. 


function msdos (command_line : string) 
return errors.extended_errors; 


If the specified command_line is an empty string (“”) then anew interactive command line interpreter 
is invoked. To return to the calling program, type the command exit. 


This call corresponds to Interrupt 16#21#, function 16#4B#. 
Possible errors are: 
e errors.file_not_found 
e errors.access denied 
e errors.insufficient_memory 
e errors.invalid_set_strings 
e errors.invalid_format 
An example of using package program_cont rol with function msdos follows. 
~— Redirect directory listing to a file. 


with program_control, 
errors, 
tty; 

use program_control; 


procedure list_exe is 


65 DOS Environment Library User’s Guide 


Package program_control 


status : errors.extended_errors; 
begin 
status := msdos ("DIR *.EXE >EXELIST.TXT”) ; 
if status /= ok then 
tty.put ("Error is : ” & 
errors.extended _errors’image (status) ) ; 
end if; 
end; 


16.9 Procedure Get_Environment_Variable 


Procedure get_environment_variable obtains the value associated with a particular environment 
variable. 


procedure get_environment_variable ( 
variable _ name : string; 
value : out string; 
last : out natural 
); 
The value of the environment variable, if found, is returned in value. The procedure raises the exception 
constraint_error if value is too small to hold the value of the environment variable. 


Last is set to the index position of the last character in value. Last is set to zero if the specified vari- 
able_name is not in the environment. 
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| 


Package revision provides a facility for determining the revision (version) number of PC-DOS. 
SPECIFICATION 


package revision is 
incorrect _dos_version : exception; 


type number is 
record 
major : natural; 
minor : natural; 
end record; 


function dos return number; 
function dos return natural; -- majoz version only 


end revision; 
17.1 Exception Incorrect_Dos_Version 


Exception incorrect_dos_versionis raised when a system function is invoked that is available only 
on a later release of PC-DOS than is present on the system. 


17.2 Function Dos 


The overloaded dos functions are disambiguated by the retumn type. Either a complete revision number 
may be obtained in the composite type number or just the major revision number may be obtained. 


17.2.1 Returning Complete Revision Number 


The first version of function dos retums the complete version number of the host operating system. 
function dos return number; 
The version number is obtained during package elaboration through interrupt 16#21#, function 16#30#. 


If the antiquated version 1 PC-DOS environment is detected then the exception incorzrect_dos_ver- 
sion is raised. 


17.2.2 Returning Major Revision Only 


The second version of function dos retums the major version number of PC—DOS. 
function dos return natural; -~ Major Version Only 
The version number is obtained during package elaboration through interrupt 16#21#, function 16#30#. 


If the antiquated version 1 PC-DOS environment is detected then the exception incorrect_dos_ver- 
sion is raised. 


An example of using package revision with function dos follows. 
-- determine if DOS version is lower than 3.0 


with text _io; 
procedure check_revision is 
begin . 
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if revision.dos < 3 then i 
text_io.put_ line (“Raising Version Exception”) ; 
raise revision.incorrect_dos_ version; 
end if; 
end; 
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Package time provides procedures to get and set the current system date and time. 
SPECIFICATION 7 
package time is 


subtype hours_range is natural range 0 .. 23; 
subtype minutes range is natural range 0 .. 59; 
subtype seconds range is natural range 0 .. 59; 
subtype hundredths_range is natural range 0 .. 99; 
subtype months_range is positive range 1 . 12; 
subtype days_range is positive range 1 rere 2 be: 
subtype years_range is positive range 1980 .. 2099; 


type day_of week is ( 
sunday, monday, tuesday, wednesday, 
thursday, friday, saturday | 

); 

type months is ( 
january, february, march, april, 
may, june, july, august, 
september, october, november, december | 


); 
type packet is 


record 
hours : hours range; 
minutes : minutes_range; 
seconds : seconds_range; 
hundredths : hundredths range; 
year : years range; 
month : months_range; 
day : days range; 

end record; 

procedure set ( 

hours : hours_range; 
minutes |: minutes_range; 
seconds : seconds range; 
hundredths : hundredths_range := 0 


); 
procedure get ( 


hours : out hours_range; 
minutes : out minutes_range; 
seconds : out seconds_range; 


hundredths : out hundredths_range 


); 
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procedure set ( 
month : months range; 
day =: days range; 
year : years range 


); 
procedure get ( 


month : out months range; 
day : out days range; 
year : out years range; 


days name : out day of week 
); 


function get return packet; 
type time format is ( 


long, —- 03:00:00 Am 
military, —~- 03:00:00 
short, —— 03:00 

none ; 


); 
type date format is ( 
long, —~ December 23, 1986 
month day year, -- 12/23/86 
day month year, -~- 23-DEC-86 
none 
); 
function image ( 


time : packet; 
time_notation : time format := long; 
date notation : date_format := long 
) return string; 
end time; 


18.1 Procedure Set 


The overloaded set procedures are disambiguated by their parameters. The first version sets the time of day; 
the second version sets the date. 


18.1.1 Setting Time of Day 


The first version of procedure set sets the system clock to a specified hour, minute, second, and hundredth 
of second. 


procedure set ( 


hours : hours _range; 
minutes : minutes_range; 
seconds : seconds range; 


hundredths : hundredths range := 0 
); . 
This call corresponds to Interrupt 16#21#, function 16#2D#. 
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An example follows. 
~- set the system time to 10:20:30. 


with time; 
use time; 
procedure set_time is 
begin 
set (hours => 10, 
minutes => 20, 
seconds => 30, 


Hundredths => 0); 
end; 


18.1.2 Setting Date 


The second version of procedure set sets the system clock to a specified date. 


procedure set ( 
month : months_range; 
day : days_range; 
year : years range 
); 
This call corresponds to Interrupt 16#21#, function 16#2B#. 
An example follows. 


—- set the system date to July 27, 1986. 
with time; 
use time; 
procedure set_date is 
begin 
set (month => 7, 
day => 27, 
year => 1986); 
end; 


18.2 Procedure Get 


The overloaded get procedures are disambiguated by their parameters and/or return type. The first version 
obtains the time of day; the second version obtains the date; the third version retums a record containing both 
time and date. a 


18.2.1 Getting Time of Day 


The first version of procedure get obtains the time of day from the system clock. 
procedure get ( : 


hours : out hours range; 
minutes : out minutes range; 
seconds : out seconds_range; 


hundredths : out hundredths_range 
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This call corresponds to Interrupt 16#21#, function 16#2C#. 


18.2.2 Getting the Date “4 


The second version of procedure get obtains the date from the system clock. 
procedure get ( 


month : out months range; 
day : out days range; 
year : out years range; 


days name : out day of week 
); ; 


This call corresponds to Interrupt 16##21#, function 16#2A#. 
An example follows. 


-- get the current date and display the days name. 


with text_io, 


time; 
procedure display day is 
mon : months_range; 
day : days range; 
yz 2: years range; 
today : day of week; 
begin “a 
time.get (mon, day, yr, today); 5 
text_io.put_line (day_of week’image (today) ); 
end; 


18.2.3 Getting Both Date and Time 


The third version of procedure get obtains both the date and time from the system clock. 
function Get return Packet; 
This call simply merges information from the date and time get procedures. - 


-~ Display the current date and time 

—~ in the form "23-DEC-86 03:00:00”. 

with tty, 

time; 
procedure todays date is 
begin 
tty.put_line(time.image( 

time => time.get, 
time_notation => time.military, 
date_notation => time.day_month_year 
) , : 


; a“ 
end todays date; 
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18.3 Function Image 


Function image retums a string representation of an object of type packet in a specified format. 
function image ( 


time : packet; 
time_notation : time format := long; 
date_notation : date_format := long 


) return string; 
There is no corresponding DOS function. 
For an example, refer to the previous section on function get. 
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Package tty provides operations on the console terminal display and keyboard. 


This package can be used in place of text __io under some circumstances. Package thy links in faster than 
text_io and calls to the tty subprograms run faster. 


SPECIFICATION 


with common_display types; 
use common display types; 
package tty is 


type shift status_record is” 


record 

insert : boolean; 
caps_lock =: boolean; 
num_lock : boolean; 
scroll_lock : boolean; 
alt shift : boolean; 


ctrl_shift : boolean; 
left_ shift : boolean; 
xight_shift : boolean; 
end record; 


procedure clear screen; 


procedure put (char : character); 


procedure put (str : string); 
procedure put ( 
row : row_range; 
column : column range; 
item : string; 
underline : boolean := false; 
reverse video : boolean 7 false; 
blink : boolean := false; 
intensity : boolean := false 


); 
procedure put ( 


row | : row_range; 
column : column range; 
item : string; 


foreground : color ; 
background : background_color; 
blink : boolean := false 
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procedure put ( 


row : xow_range; 
column : column range; 
item : character; 
underline : boolean := false; 
reverse _ video =: boolean := false; 
blink : boolean :2 false; 
intensity : boolean :@ false 
); 

procedure put ( 
zow > row _range; 
column : column range; 
item : character; 


foreground : color; 
background : background color; 
blink : boolean := false 
; 
procedure put line (str : string); 


-- Keyboard Functions 


_ function shift_status return shift_status_record; 
function char_ready return boolean; 


procedure get ( 
scan_code : out byte; 
char : out character 
); 
function get ( 
no_echo : boolean := false; 
direct : boolean := false; 
clear : boolean := false 
) veturn character; 


procedure get (str : out string; last : out natural); 
end tty; 
19.1 Procedure Clear_Screen 


Procedure clear_screen clears the currently active wey 
procedure clear_screen; 
This call corresponds to Interrupt 16#10#, function 16#06#. 


19.2 Procedure Put . 
The overloaded put procedures provide various means of writing to the console display. 
19.2.1 Put Character 


The first version of procedure put writes one character to the standard output device. 
procedure put (char : character) ; 
This call corresponds to Interrupt 16#21#, function 16#02#. 
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19.2.2 Put String 

The second version of procedure put writes the specified string to the standard output device. 
procedure put (str: string) ; 

This call corresponds to Interrupt 16#21#, function 16#40#. 

19.2.3 Put String, Non—Color Attributes 


The third version of procedure put writes a string, item, with the specified non-color display attributes, 
to the specified cursor position in the currently selected page. 


procedure put ( 


row : row_range; 

column : column_range; 

item : string; 

underline : boolean := false; 
reverse _video : boolean := false; 
blink | : boolean := false; 
intensity : boolean := false 


); 
If the output string reaches the end of the bottommost screen line, the screen is automatically scrolled up one 
line. This may destroy any statically formatted screen display. 


The initial row and column position must be valid forthe current display mode. If the position is invalid, 
the results are unpredictable. 


This call corresponds to Interrupt 16#10#, function 16#0E#. 
19.2.4 Put String, Color Attributes 


The fourth version of procedure put writes a string to the specified cursor position in the currently selected 
page with the specified color display attributes. 


procedure put ( 


row : row_range; 
column : column_range; 
item : string; 


foreground : color ; 
background : background_color; 
. blink : boolean := false 
); 
If the output string reaches the end of the bottommost line, the screen is automatically scrolled up one 
line. This may destroy any statically formatted screen display. 


The initial row and column position must be valid forthe current display mode. If the position is invalid, 
the results are unpredictable. : 


This call corresponds to Interrupt 16#10#, function 16#0E#. 
19.2.5 Put Character, Non—Color Attributes 


The fifth version of procedure put writes a character to the specified cursor position in the currently selected 
page with the specified non-color display attributes. : 
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Procedure put ( 


row 2 xOw_range; 

column : column range; 

item : Character; 
underline : boolean :@ false; 
reverse video =: boolean := false; 
blink : boolean := false; 
intensity : boolean >= false 


); 


If the output character reaches the end of the bottommost line, the screen is automatically scrolled up one 
line. This may destroy any Statically formatted screen display. 


The initial row and column position must be valid forthe current display mode. If the position is invalid, 
the results are unpredictable. 


This call corresponds to Interrupt 16#10#, function 16#0E#. 
19.2.6 Put Character, Color Attributes 


The sixth version of procedure put writes a character to the specified cursor position in the currently selected 
page with the specified color display attributes. 


procedure put ( 


row : row _range; 
colum -: column range; 
item : character; 


foreground : color; 

background : background color; 

blink : boolean := false 
); 


If the output character reaches the end of the bottommost line, the screen is automatically scrolled up one 
line. This may destroy any statically formatted screen display. 


The initial row and colwmn position must be valid for the current display mode. If the position is invalid, 
the results are unpredictable. 


This call corresponds to Interrupt 16#10#, function 16#0E#. 


19.3. Procedure Put_Line 
Procedure put_line writes the specified string to the standard output device followed by a carriage—re- 
tum, line-feed sequence. 
procedure put_line (str : string) ; 
This call corresponds to Interrupt 16421, function 16#40#. 


19.4 Function Shift_Status 


The function shift_status retums the present shift status of the keyboard. 

function shift _status return shift_status_record; 
This status record corresponds to the ROM BIOS flag at address 0000:0417H. 
This call corresponds to Interrupt 16#16#, function 16#02#. 


DOS Environment Library User’s Guide -78 


Package tty 


19.5 Function Char_Ready 


The function chaxz_ready determines if a character is ready to be read. 
function char_ready return boolean; 
This call corresponds to Interrupt 16#16#, function 16#01#. 


19.6 Subprogram Get 
The overloaded get subprograms provide various means of reading from the console keyboard. 
19.6.1 Raw Get 


The first version of get obtains the scan code and raw character from the keyboard. 


procedure get ( 
scan_code : out byte; 
char : out character 


); 
This call corresponds to Interrupt 16#16#, function 16#00#. 


19.6.2 Get Character 


The second version of get retums a character from the standard input device by the specified method. 
function get ( 


no_echo : boolean := false; 
direct : boolean := false; 
clear : boolean := false 


) return character; 
If the clear flag is set then the input buffer is first cleared before the next character is input. 


If the no_echo and direct flags are both set, then Interrupt 16#21#, function 16#07# is used. Characters 
are read without being echoed to the standard output device. No special action is taken if a Control-C 
(AC) is detected. 


If the no_echo flag alone is set then Interrupt 16#21#, function 16#08# is used. Characters are read without 
being echoed to the standard output device. 


If the direct flag is set then Interrupt 16#21#, function 16#06# is used. No special ‘action is taken if a 
Control—-C (4C) is detected. If no character is ready for input then a null character (ASCII NUL) is 
returned. 


19.6.3 Get String 


The third version of get reads a string from the standard input device. 
procedure get (str : out string; last : out natural); 

This call performs a buffered read until a carriage return is detected. 

Parameter last is the index position of the last valid character in the retumed string. 

This call corresponds to Interrupt 16#21#, function 16#0A#. 
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Chapter 20 Package Video 


Package video provides various output and control functions for the Monochrome, Color Graphics, and 
Extended Graphics Adapter Cards. 


The Color/Graphics Adapter has eight display pages (0.. 7) in40 column by 25 line text modes and four dis- 
play pages in the 80 column by 25 line text modes. The Monochrome adapter has only one display page. 
Specifying an invalid display page (i.e. a display page that is not defined for the current text display 
mode) has unpredictable results. 

Some of the overloaded subprograms are disambiguated by the type of character that they accept: either 
standard. character or common_display_ types. extended_ascii. Be aware that the Ada 
pre-defined type character supports only-seven—bit ASCII characters. If it is necessary to manipulate 
all eight bits of a byte, then pragma suppress should be used when using objects of type character (to 
avoid the exception constraint_erroz), OF the type extended_asoii should be used. 


SPECIFICATION 


with common _display_types; 
use common_display_ types; 
package video is 


type video mode is ( 

text40_bw, 
text40_ co, 
text80_bw, 
text80_co,. 
graphic _4 color, 
graphic _4 grey, 
graphic _bw, 
text80_ bw ma, 
gxraphic_color_high, 
gxaphic_med_ega, 
graphic high _ega, 
graphic extra_ega, 
color_extra_ega 

); 

type pixel value is . 

record 
xor_bit : boolean := false; 
pixel_color : gxaphic_ color := background; 
end record; 


procedure set (mode : video_mode) ; 
procedure get_mode ( 

width ;: out byte; 

mode : out video mode; 

page : out display page 

i; 
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procedure get light pen ( 


); 


txiggered : out boolean; 
Pixel_row : out integer; 
pixel_col : out integer; 
char_row : out integer; 
char col : out integer 


procedure set_active (page : display . page); 


~- Windowing functions 


procedure scroll _ up ( 


); 


number of lines 

upper_row : 

left_column 

lower_row 

right_column 

filler attribute: 
foreground => 
background => 
blink => 

) 


procedure scroll down 


): 


number_of lines 
upper row 
left_column 
lower_row 
zight_column 


foreground => 

background => 

blink => 
) 


: byte; 


row_range; 


: column range; 
>: row _xange; 
: column range; 


display attribute 
white, 

black, 

false 


( 


: byte; 

: row_range; 

: column _ range; 
: xow_range; 

: column range; 
filler attribute : 


display attribute 
white, 
black, 
false 


procedure clear_screen; 


procedure read char ( 


); 


item 
attribute : 
page 


: out extended_ascii; 
out. display attribute; 
: display page := 0 
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procedure write_char ( 


item : character; 
repeat_count : natural; 
attribute : display_attribute := 


foreground => white, 
background => black, 


blink => false 
; 
page ; display _page := 0 
; 
procedure write_char ( 
item : extended_ascii; 
repeat_count : natural; 
attribute : display_attribute := ( 
foreground => white, 
background => black, 
blink => false 
); 
page : display _page := 0 


); 


procedure write_char ( 


item : character; 
repeat _count : natural; 
page : display page 


); 


procedure write_char ( 


item : extended_ascii; 
repeat_count : natural; 
page : display page 


); 
procedure set_color_palette (to_color 
procedure write_tty (item : character) ; 


procedure write tty (item : 


-- Graphics Mode Only 

procedure set_color_palette ( 
to_palette : color_palette 
; 


procedure write tty ( 
item : character; 
which color : pixel_value 
)? 


Package video 


: color); 


extended_ascii) ; 


83 DOS Environment Library User’s Guide 


Package video 


procedure write pixel ( 
Pixel_color =: pixel_value; 
pixel_row > natural; 
pixel_column : natural 
); 
function read_pixel ( 
pixel_row > natural; 
pixel_column : natural 
) xeturn pixel_value; 
procedure write_graphic char ( 
item : character; 
attribute : pixel value; 
repeat_count : natural 
); 
end Video; 


20.1 Type Video _Mode 
The enumeration elements of video_mode are described in Figure 20.1. 
20.2 Procedure Set 


Procedure set sets the current video display mode. 
procedure set (mode : video_mode) ; 
This call corresponds to Interrupt 16#10#, function 16#00#. 
An example follows. 
~- set the video mode to 25x40 color text 


video.set (mode => text40_co) ; 
20.3 Procedure Get_Mode 


Procedure get_mode obtains the current display mode, screen width, and page. ° 
procedure get_mode ( 
width : out byte; 
mode : out video _mode; 
page : out display page 
); 
This call corresponds to Interrupt 16#10#, function 16#0F#. 


20.4 Procedure Get_Light Pen 


Procedure get_light_pen obtains the light pen’s current status and position. 
procedure get_light pen ( 
triggered : out boolean; 
pixel_row : out integer; 
pixel_col : out integer; 
char_row : out integer; 
char col : out integer 
); 
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This call corresponds to Interrupt 16#10#, function 16#04#. 
20.5 Procedure Set_Active 


Procedure set_active scts the active video display page. 
procedure set_active (page : display page) ; 
Valid display pages are: 
e 0.. 7 for text40_bw (mode 0), text40_co (mode 1) Color/Graphics Adapter 
e 0.. 3 fortext80_bw (mode 2), text80_co (mode 3) Color/Graphics Adapter 
e 0.. 7 for text80_bw (mode 2), text80_co (mode 3) Extended Adapter 
Setting an invalid page for the current mode has unpredictable results. 
Procedure set_active does not apply to a Monochrome display. 
This call corresponds to Interrupt 16#10#, function 16#05#. 
An example of using package video with procedure set_active follows. 
-— set the active display page to page 1. 


video.set_active (page => 1); 
20.6 Procedure Scroll_Up 


Procedure scxo11_up scrolls a specified window up and initializes the new lines with the filler_attribute. 


procedure scroll_up ( 
number_of_lines : byte; 


upper_xrow : row _range; 
left_column : column_range; 
lower_zow : row_xrange; 
right_column : column_range; 
filler_attribute : display attribute := ( 


foreground => white, 

background => black, 

blink => false 

) 
); . 

If number_of_lines is zero then the entire window is blanked and initialized with the filler_attribute. 
Lines scrolled above the top of the window are lost. . oT 
Scrolling is only valid for the currently selected display page. 
Scrolling invalid windows has unpredictable results. 
This call corresponds to Interrupt 16#10#, function 16#06#. 
An example of using package video with procedure scroll_up follows. 


-- define a window with corners 5,10 and 15,30 (row, col) 
-- and scroll it up 4 lines filling in the bottom lines 
-- with a blue background. ss 

with video, common_display_types; 

use common_display types; i 
procedure’ make_window is : 
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£ill_attr : display attribute; 
begin ° 


video.clear _screen; 
£ill_attr.background := blue; 
video. scroll up ( 

number_of lines => 4, 


upper row => §, 
left_column => 10, 
lower_xrow => 15, 
right column => 30, 


filler_attribute => f111 attr 
); 
end; 


20.7 Procedure Scroll Down 


Procedure scroll_down scrolls a specified window down and initializes the new lines with the filler_at- 
tribute. 


procedure scroll _ down ( 
number of lines =: byte; 


upper_row > xow_xange; 
left_column : column range; 
lower_row > row _range; 
xright_column : Ccolumn_range; 


filler_attribute : display attribute := ( 

foreground => white, 

background => black, 

blink => false 

) 
); 
If number_of_lines is zero then the entire window is blanked and initialized with the filler_attribute. 
Scrolling is only valid for the currently selected display page. 
Lines scrolled below the bottom of the window are lost. 
Scrolling invalid windows has unpredictable results. 
This call corresponds to Interrupt 16#10#, function 16#07#. 
20.8 Procedure Clear Screen 
Procedure clear_screen clears the currently selected display page. 
procedure clear screen; 

This call corresponds to Interrupt 16#10#,. function 16#06#. 


An example of using package video with procedure clear screen follows. 
“~~ erase the screen. 


video.clear_screen; 


20.9 Procedure Read | Char 


Procedure read_char allows eight-bit characters (bytes) to be read. Procedure zead_char obtains the 
character and its attribute from the current cursor position in the specified display page. 
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procedure read char ( 


item 2 out extended_ascii; 
attribute : out display_attribute; 
page : display_page := 0 


); 
This call corresponds to Interrupt 16#10#, function 16#08#. 
An example of using package video with procedure read_char follows. 
-- get the character and attribute from display 
-- page zero. 


declare 

char : extended_ascii; 

attr : display_attribute; 
begin 

video.read char (item => char, attribute => attr); 
end; 


20.10 Procedure Write_Char 


The overloaded write_char procedures are distinguished by the presence or absence of the attribute 
parameter and by the type of character written. 


20.10.1 Write With Attributes 
The first and second versions of procedure write_char write a character and its attribute at the current 
cursor position in the specified display page. i 
Seven~Bit ASCII 
The first version of procedure write_chaxr writes a seven-bit ASCII character. 
procedure write_char ( 


item : character; 
repeat count : natural; 
attribute : display attribute := ( 
foreground => white, 
background => black, 
blink => false 
); 
page : display page 72 0 


); 
The cursor position is not updated. 
The results are unpredictable if the repeat_count causes characters to be written past the right side of the 
screen. 
This call corresponds to Interrupt 16#10#, function 16#09#. 
An-example which uses package video with procedure write_char follows. 


-~- Write a string of 10 happy faces (ASCII ordinal 1) at 
-- the current cursor position. 


with video; 
procedure write_happy is 
begin 
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video.write char ( 

item => character’val (1), 
repeat_count => 10 
); 
end; 


Eight~Bit Characters 


The second version of procedure wxite_char writes an eight—bit character, 
procedure write char ( 


item > extended ascii; 
repeat_count : natural; 
attribute : Gisplay attribute := ( 


foreground => white, 
background => black, 
blink => false 
); 
page : display page := 0 
es 


The cursor position is not updated. 


The results are unpredictable if the repeat_count Causes characters to be written past the right side of the 
screen. ' 


This call corresponds to Interrupt 16#10#, function 16#09#. 
20.10.2 Write With Previous Attributes 


The third and fourth versions of procedure write_char write the character at the current cursor position 
in the specified display page with the already—present attributes. 


Seven—Bit ASCII 


The third version of procedure write_char writes a seven— bit ASCII character. 
procedure write char ( 


item : character; 
xepeat_count : natural; 
page : display page 


); 
The character receives the attribute of the previous character at that position. 
The cursor position is not updated. 


The results are unpredictable if the repeat_count causes characters to be written past the right side of the 
screen. 


This call corresponds to Interrupt 16#10#, function 16#0A#. 

Eight~Bit Characters 

The fourth version of procedure write_char writes eight~bit characters. 
procedure write char ( 


item 2 extended ascii; 
repeat_count : natural; 
page : display page 


); 
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The character receives the attribute of the previous character at that position. 
The cursor position is not updated. . 


The results are unpredictable if the repeat_count causes characters to be written past the right side of the 
screen. o 


This call corresponds to Interrupt 16#10#, function 16#0A#. 
20.11 Procedure Set_Color_Palette 


The overloaded set_color_palette procedures are distinguished by a color parameter appropriate 
to the display device. 


20.11.1 Text or Graphics 
The first version of procedure set_color palette scis the background and border color in graphics 
modes, or sets just the border color in text modes. ~ 
procedure set_color_palette (to_color : color); — 
This call corresponds to Interrupt 16#10#, function 16#0B#. 
An example which uses package video with procedure set_color_palatte follows. 
-— set the text modes border color to blue. 


video.set_color_palette (to_color => blue); 
— Note: must already be in a text mode. 


20.11.2 CGA 


The second version of procedure set_color_palette sets the specified palette for the Color/Graphics 
Adapter. 


procedure set_color_palette (to ) palette : color _ palette) ; 
This call is valid only inGraphic_4 Color mode. 
This table indicates what colors are presented: 


Color_Pallette Graphic_Color 


Background = Same as current 
Colorl = Green 

Color2 = Red 

Color3 = Brown 


Background = Same as current 
Color! = Cyan 

Color2 == Magenta 
Color3 = White 


This call corresponds to Interrupt 16#10#, function 16#0B#. 
An example follows. 


-——- set the color palette to palette 1. 


video.set_color_palette (to_palette => 1); 
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20.12 Procedure Write_Tty 


20.12.1 Write To Current Display Page 


The overloaded write tty procedures are disambiguated by parameters appropriate to the output device. 


The first and second versions of procedure write_tty write a character to the currently active display page 
and updates the cursor position. 


Seven~Bit ASCII 


The first version of procedure write_tty writes seven—bit ASCII characters. 
procedure write tty (item : character) ; 
This call should be made in text modes only. 
Appropriate action is taken when these special characters are written: 
e bell (ASCII BEL) 
e linefeed (ASCII LF) 
@ carriage return (ASCII CR) 
© backspace (ASCII BS) 
The display attribute is taken from the previous character at that location. 


If the cursor reaches the end of the bottommost screen line, the screen automatically scrolls up and 
the cursor is positioned at the “next” line. 


This call corresponds to Interrupt 16#10#, function 16#0E#. 
An example which uses package video with procedure write-—tty follows. 
~- write out the the string "this is a test” 


with video; 
procedure write tty test is 


str : string (1 .. 14) := "this is a test”: 
begin 
for i in str’ range loop 
video.write tty (item => str (i)); 
end loop; 
end; 


Eight-Bit Characters 


The second version of procedure write_tty writes eight—bit characters. 
procedure write tty (item : extended ascii) ; 
Appropriate action is taken when these special characters are written: 
© bell (ASCII BEL) 
@ linefeed (ASCII LF) 
© carriage return (ASCII CR) 
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e backspace (ASCII BS) 
The display attribute is taken from the previous character at that location. 
If the cursor reaches the end of the bottommost screen line, the screen automatically scrolls up and 
the cursor is positioned at the “next” line. 
This call corresponds to Interrupt 16#10#, function 16#0E#. 
An example follows. 
-— write out the the string "this is a test” 


with video; 
procedure write_tty_test2 is 

str : string (1 .. 14) := "this is a test”; 
begin 


for i in str’xrange loop 
video.write tty (item => character’pos (str (4))); 
end loop; 
end; 


20.12.2 Write Graphic Character 


The third version of procedure write tty writes a graphic character with the specified attribute. 


procedure write tty ( 
item : character; 
which color : pixel_value 
); 
The results are unpredictable if the current display mode is not a graphic mode. 


If the cursor reaches the end of the bottommost screen line, the screen automatically scrolis up and 
the cursor is positioned at the “next” line. 


This call corresponds to Interrupt 16#10#, function 16#0E#. 
20.13 Procedure Write_Pixel 


Procedure write pixel tums on a pixel at the specified location. 
procedure write . pixel ( 

pixel_color : pixel_value; 

pixel_row : natural; 

pixel_column : natural 

); 

Valid display locations depend on the current graphic mode. The results are unpredictable for invalid 
coordinates. 


This call corresponds to Interrupt 16#10#, function 16#0C#. 
20.14 Function Read_Pixel 


Function read_pixel obtains the pixel_value for the specified position. 
function read | pixel ( 
pixel_row : natural; 
pixel_column : natural 
) return pixel_value; 


91 DOS Environment Library User’s Guide 


Package video 


Valid display locations depend on the current graphic mode. 
This call corresponds to Interrupt 16#10#, function 16#0C#. 


20.15 Procedure Write_Graphic_Char 


Procedure write_graphic_char writes a graphic character at the current cursor location. 


procedure write_graphic char ( 
item : character; 
attribute >: pixel_value; 
repeat_count : natural 
); 
The cursor position is not updated. 
This call is valid only in graphics modes. 


The results are unpredictable if the repeat_count causes characters to be written past the right-side of the 
screen. 


This call corresponds to Interrupt 16#10#, function 16#0A#. 
An example which uses package video with procedure write_graphic_ char follows. 


-- write the 10 graphic '?’ characters, 
~- wait 2 seconds then erase it. 

-~ (graphics mode is assumed) 

with video, common_display types; 

use video, common_display types; 


procedure graphic test is 
attr : pixel_value; 
begin 
attr.pixel_ color := colori; 
write graphic char ( 
item => '?!, 
attribute => attr, 
repeat_count => 10 
); 
delay 2.0; 
attxr.xor bit := true; 
write graphic char ( 
item => '?', 
attribute => attr, 
repeat_count => 10 
); 
end; 
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Video Mode 

cae a 
ics Adapter (CGA) 

fexti0_o 

——rexto_bw || 2580 B/W text (CGA) _ 


graphic_4 color 200x320 4 color graphics 
(CGA) 


graphic_4_grey [OSH =| ~—_200x3204 grey (CGA) 
graphic_bw | O6H =| _~—_ 200x640 2 color (CGA) 


text80_bw_ma 07H 25x80 B/W text, Monochrome 
Adapter 
graphic_color_high 0AH 200x640 color graphics, Ex- 
tended Adapter (EGA) 
graphic_med_ega 200x320 16 color graphics 
(EGA) 
graphic_high_ega 200x640 16 color graphics 
(EGA) 
graphic_extra_ega OFH 350x640 monochrome graphics 
(EGA) 
10H 350x640 four color or 16-color 
graphics (EGA) 


Figure 20.1Video Modes 
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* agar files, 4 
* int files, 4 
* lib files, 4 


A 


absolute_disk. See package absolute_disk 


Ada for Programmers, 2 

ada.lib, 3 

allocate, procedure, S8—59 
amount of memory installed, 60 
ANSI/MIL-STD-1815A (LRM), 2 
ASCII BEL, 90 

ASCII BS, 90, 91 

ASCII CR, 90 

ASCII LF, 90 


B 


bin directory, 4 


border color 
graphies, 89 
text, 89 


box style, selecting, 11 

box, package. See package box 
boxdemo.ada file, 4 
break_status, function, 64 
buffers, flushing, 25 

byte input, 61—62 


Cc 


calls to interrupt vectors, 55—56 
cdup_filehandle, procedure, 52 
CGA (color graphics adapter), 89 
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change_to, function, 22-—23 

char_ready, function, 79° 

character set for IBM PC, 13 

characters for drawing boxes, 11—14 

clear_screen, procedure, 76, 86 

clearing the screen, 76, 86 

close, function, 45—46 

color graphics card, 81 

color, setting palette, 89 

color_extra_ega, 93 

common_display_types. See package common_dis- 
play_types 3a 

common_display_types.extended_ascii, 81 

cooked, function, 46 

create, procedure, 41—42 

create_new, procedure, 44 

create_temporary, procedure, 42—43 

current directory with procedure create_temporary, 43 

current_name, function, 23——24 


cursor 
making invisible, 18 
manipulating, 17—20 
moving, 18 
moving down, 19 
moving left,19 
moving right, 19—-20 
moving up, 19 
positioning, 18-19 


cursor, package. See package cursor 


D 


date 
getting, 72 
setting, 71 


decreasing memory block, 59 
delete, function, 48 


directories 
changing, 22—23 
making, 21—22 
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obtaining pathname, 23—24 
removing, 22 


directory, package. See package directory 
disk drive 
obtaining disk information, 27—28 
obtaining information about, 26 
requesting ID, 26 
setting default, 26 
verifying read—after—write, 26, 27 
disk, package. See package disk 
disk_types, package, 29 
display mode, 84 
DOS Environment Library, installing, 3—6 
dos, function, 67 
dosenv directory, 3, 4 
down, procedure, 19 
draw, procedure, 11—14 
dup_filehandle, 52 


E 


e\stuff directory, 3 

eight—bit characters, 88, 90 
eight-bit characters, reading, 86 
envdisp, 5 

envdisp.ada file, 4 

equipment, package, 31 

errors, package. See package errors 
exception constraint_error, 81 
exception incorrect_dos_version, 67 
execute, function, 65 

extended graphics adapter card, 81 
extended status information, 33 


F 


file_io, package. See package file_io 
files 

closing, 45—46 

creating, 44 

deleting, 48 

opening, 45 

reading from, 46 
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renaming, 48—49 
writing to, 47 


files, creating, 41—42 
find_first, procedure, 52—53 
find_next, procedure, 53—54 
flags component, 56 

function break_status, 64 
function change-to, 2223 
function char_ready, 79 
function close, 45—46 
function cooked, 46 

function current_name, 23—24 
function delete, 48 

function dos, 67 

function execute, 65 

function get_default, 26 
function image, 73 

function in_byte, 61 

function in_word, 61 

function installed, 60 
function list, 31 

function make, 21, 58 


' function msdos, 65—66 


function raw, 46 

function read_pixel, 91—92 
function release, 59 
function remove, 22 
function rename, 48—49 
function resident_quit, 64 
function segment_prefix, 64 
function set_attributes, 51 
function set_default, 26 
function set_file_time, 51 
function shift_status, 78 
function used, 60 

function verification_is_on, 27 


G 


get string, 79 


get, procedure, 71-——72 


get, subprogram, 79—80 
get_allocation_info, procedure, 26 
get_attributes, procedure, 50—51 
get_default, function, 26 
get_environment_variable, procedure, 66 
get_extended_info, procedure, 34 
get_file_time, procedure, 51—52 
get_free_space, procedure, 27—28 
get_light_pen, procedure, 84—85 
get_mode, procedure, 84 
get_position, procedure, 18—19 
get_return_code, procedure, 64 
graphic characters, writing, 91, 92—93 
graphic_4_color, 93 
graphic_4_color mode, 89 
graphic_4_grey, 93 

graphic_bw, 93 
graphic_color_high, 93 
graphic_extra_ega, 93 
graphic_high_ega, 93 
graphic_med_ega, 93 


H 


host operating system version number, 67 


image, function, 73 

IN instruction, 61 

in_byte, function, 61 

in_word, function, 61 

incorrect_dos_version, exception, 67 
increasing memory block, 59—60 

inhibit, procedure, 18 

install directory, 4 

INSTALL program, 3 

installed, function, 60 . 
installing the DOS Environment Library, 3—6 
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interrupt 16#10# 
function 16#00#, 84 
function 16#01#, 18 
function 16#02#, 18, 19 
function 16#03#, 19 
function 16#04#, 85 
function 16#05#, 85 
function 16#06#, 76, 85—86 
function 16#07#, 86 
function 16#09#, 87, 88 
function 16#0A#, 88, 89, 92 
function 16#0B#, 89 
function 16#0C#, 91, 92 
function 16#0E#, 77, 78, 90, 91 
function 16#0F#, 84 


interrupt 16#11#, 31 


interrupt 16#16# 
function 16#00#, 79 
function 16#02#, 78, 79 


interrupt 16#21# 
function 16#02#, 76 
function 16#06#, 79 
function 16#07#, 79 
function 16#0A#, 79 
function 16#0D#, 25 
function 16#0E#, 26 
function 16#12#, 60 
function 16#19#, 26 
function 16#1C#, 26 
function 16#2A#, 72 
function 16#2B#, 71 
function 16#2C#, 72 
function 16#2D#, 70 
function 16#2E#, 26 
function 16#31#, 64 
function 16#33#, 64 
function 16#36#, 27 
function 16#3C#, 41 
function 1643D#, 45 
function 16#3E#, 46 
function 16#3F#, 47 
function 16#40#, 48, 77, 78 
function 16#41#, 48 
function 16#42#, 49 
function 16#43#, 50, 51 
function 16#44#, 46 
function 16#45#, 52 
function 16#46#, 52 
function 164#48#, 58 
function 16#49#, 59 
function 16#4A#, 60 
function 164#4B#, 65 
function 16#4C#, 64 
function 16#4D#, 64 
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function 16#4E#, 53 
function 16#54#, 27 
function 16#56#, 49 
function 16#57#, 51 
function 16#59#, 35 
function 16#5A#, 42, 43 
function 16#5B#, 44 


interrupt 16#25#, 7—8 

interrupt 16#26#, 8 

interrupt vectors, calls to, 55 

interrupt, package. See package interrupt 


L 


left, procedure, 19 


light pen 
Position, 84A—85 
Status, 84—85 


Inlib command, 3 


make, function, 21, 58 

memory block, releasing, 59 

memory, allocating and deallocating, 57—60 
memory, package. See package memory 


Microsoft MS-DOS Operating System Programmer's 
Reference Guide, 2 


modify, procedure, 59-—60 
monochrome graphics card, 81 


move, procedure, 18 
move_file_pointer, procedure, 49—50 
msdos, function, 65—66 


N 


newlib command, 4 
newlib.bat file, 4 


O 


object type packet, 73 
offset, 58 
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open, procedure, 45 
OUT instruction, 62 


out_byte, procedure, 62 
out_word, procedure, 62 
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package absolute_disk, 7-—8 
procedure read, 7—8 
procedure write, 8 

package box, 914 
procedure draw, 11—14 
type part, 10 
type simple_kind, 11 
type user_definition, 11 

package common_display_types, 15—-16 

package cursor, 17—20 
procedure down, 19 
procedure get_position, 18—19 
procedure inhibit, 18 
procedure left, 19 
procedure move, 18 
procedure right, 19—20 
procedure set_size, 17—18 
procedure up, 19 

package directory, 21—24 
function change_to, 22—23 
function current_name, 23—-24 
function make, 21—22 
function remove, 22 


package disk, 25—-28 
function get_default, 26 
function set_default, 26 
function verification_is_on, 27 
procedure get_allocation_info, 26 
procedure get_free_space, 27—28 
procedure reset, 25 
procedure set_verification, 26 


package disk_types, 29 

package equipment, 31—32 
function list, 31 

package errors, 33-—36 
procedure get_extended_info, 34 


package file_io, 37—54 
function close, 45—46 
function cooked, 46 
function delete, 48 
function raw, 46 
function rename, 48—49 
function set_attributes, 51 


function set_file_time, 51 
procedure cdup_filehandle, 52 
procedure create, 41-42 
procedure create_new, 44 
procedure create_temporary, 42—43 
procedure dup_filehandle, 52 
procedure find_first, 52—53 
procedure find_next, 53—54 
procedure get_attributes, 50—51 
procedure get_file_time, 51—52 
procedure move_file_pointer, 49—50 
procedure open, 45 

procedure read, 46—47 

procedure write, 47—48 


package interrupt, 5556 
procedure vector, 5556 


package memory, 57-60 
function installed, 60 
function make, 58 
function release, 59 
function used, 60 
procedure allocate, 58-59 
procedure modify, 59-60 
procedure split, 58 


package port, 61—62 
function in_byte, 61 
function in_word, 61 
procedure out_byte, 62 
procedure out_word, 62 


package program_control, 63—66 
function break_status, 64 
function execute, 65 
function msdos, 65—66 
function resident_quit, 64 
function segment_prefix, 64 


procedure get_environment_variable, 66 


procedure quit, 64 
procedure set_break_status, 64 


package revision, 67—68 
exception incorrect_dos_version, 67 
function dos, 67 


package time, 69—74 
function image, 73 
procedure get, 71—72 
procedure set, 70 


package tty, 75 
function char_ready, 79 
function shift_status, 78 
procedure clear_screen, 76 
procedure put, 76—78 
procedure put_line, 78 
subprogram get, 79-80 
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package video, 81—94 
enumeration elements for video_mode, 93 
function read_pixel, 91—92 
procedure clear_screen, 86 
procedure get_light_pen, 84—85 
procedure get_mode, 84 
read_char, 86—87 
scroll_down, 86 


procedure set, 84 

procedure set_active, 85 - 

procedure set_color_palette, 89 
procedure write_char, 87—89 
procedure write _graphic_char, 92—-93 
procedure write_pixel, 91 


procedure write_tty, 90 
type video_mode, 84, 93 


paclib\ada.lib, 3 

part, type, 10 

parts of box, creating, 10, 11 
pathname with procedure create_temporary, 42—43 
PC-DOS version number, 67 , 
port, package, 61—62 

pragma suppress, 81 

procedure allocate, 58-—59 
procedure cdup_filehandle, 52 
procedure clear_screen, 76, 86 
procedure create, 41—42 
procedure create_new, 44 

procedure create_temporary, 42—43 
procedure down, 19 


procedure draw, 11—14 
pre-defined box types, 11—12 
selected characters for box parts, 13—14 


procedure dup_filehandle, 52 
procedure find_first, 32—53 
procedure find_next, 53—54 
procedure get, 71 

procedure get_allocation_info, 26 
procedure get_attributes, 50—51 
procedure get_environment_variable, 66 
procedure get_extended_info, 34 
procedure get_file_time, 5 1—52 
procedure get_free_space, 27—28 
procedure get_light_pen, 84—-85 
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procedure get_mode, 84 
procedure get_position, 18—19 
procedure get_return_code, 64 
procedure inhibit, 18 
procedure left, 19 

procedure modify, 59—60 
procedure move, 18 

procedure move_file_pointer, 49—50 
procedure open, 45 

procedure out_byte, 62 
procedure out_word, 62 
procedure put, 76—78 
procedure put_line, 78 
procedure quit, 64 

procedure read, 7—8, 46—47 
procedure read_char, 86—87 
procedure reset, 25 

procedure right, 19—20 
procedure scroll_down, 86 
procedure scroll_up, 85—86 
procedure set, 70, 84 
procedure set_active, 85 
procedure set_break_status, 64 
procedure set_color_palette, 89 
procedure set_size, 17—18 
procedure set_verification, 26 
procedure split, 58 

procedure up, 19 

procedure vector, 55—56 
procedure write, 8,47—48 
procedure write_char, 87—89 
procedure write_graphic_char, 92—93 
procedure write_pixel, 91 
procedure write_tty, 90 
procedure write_tty_test, 90 
program size at startup, 60 


program_control, package. See package pro- 


gram_control 
put character, 76 
put character, color attributes, 78 
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put character, non-color attributes, 77 
put string, 77 

put string, color attributes, 77 

put string, non-color attributes, 77 
put_line, procedure, 78 


quit, procedure, 64 


raw get, 79 

raw, function, 46 

read, procedure, 7—8, 46—47 
read_char, procedure, 86-—87 
read_pixel, function, 91—92 
reading eight-bit characters, 86 
registers, 55—-56 

release, function, 59 

releasing memory block, 59 
remove, function, 22 

rename, function, 48—49 

reset, procedure, 25 

resident_quit, function, 64 

return code, getting, 64 
revision.incorrect_dos_version, 43 
revision, package. See package revision 
right, procedure, 19—20 
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screen width, 84 


segment, 58 
segment_prefix, function, 64 
set procedure, 70 


set, procedure, 84 

' set_active, procedure, 85 

’ set_attributes, function, 51 
set_break_status, procedure, 64 
set_color_palette, procedure, 89 
set_default, function, 26 
set_file_time, function, 51 
set_size, procedure, 17 
set_verification, procedure, 26 
seven-bit ascii, 87, 88, 90 
shift_status, function, 78 
simple_kind, type, 11 
spilt, procedure, 58 
standard.character, 81 
status declarations, 33 
subprogram get, 79—80 
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temporary files, creating, 42—43 
terminating the calling program, 64 
test directory, 4 

text_io, 75 

text40_bw, 93 

text40_co, 93 

text80_bw, 93 

text80_bw_ma, 93 

text80_co, 93 


time of day 
getting, 71—72 
setting, 70—71 


time, package. See package time 
tty, package. See package tty 
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type character, 81 

type extended_ascii, 81 
type part, 10 

type simple_kind, 11 
type user_definition, 11 
type video_mode, 84, 93 
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up, procedure, 19 
used, function, 60 
user _definition, type, 11 
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vector, procedure, 55—56 
verification_is_on, function, 27 

video, package. See package video 
video_mode enumeration elements, 93 
video_mode, type, 84, 93 
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word input, 61-62 

write, procedure, 8, 47—48 
write_char, procedure, 87-89 
write_graphic_char, procedure, 92—93 
write__pixel, procedure, 91 

write_tty, procedure, 90 

write_tty_test, procedure, 90 

writing characters, 90 

writing to console display, 76 
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